¿Cómo puedo representar 'Autorización: Portador <token>' en una Swagger Spec (swagger.json)


112

Estoy tratando de transmitir que el esquema de autenticación / seguridad requiere configurar un encabezado de la siguiente manera:

Authorization: Bearer <token>

Esto es lo que tengo basado en la documentación de swagger :

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

Respuestas:


138

Quizás esto pueda ayudar:

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'

Puede copiarlo y pegarlo aquí: http://editor.swagger.io/#/ para ver los resultados.

También hay varios ejemplos en la web del editor Swagger con configuraciones de seguridad más complejas que podrían ayudarlo.


4
No veo cómo le dices al editor qué usuario y contraseña o token básico enviar para que puedas obtener un 200. ¿Me estoy perdiendo algo?
Rob

1
OK no importa. Aparentemente, "Autenticar" es algo en lo que puede hacer clic para obtener un formulario de inicio de sesión.
Rob

Entonces, ¿cómo establezco un valor para el token? Intenté curl -x get --header "Authorization: apiKey = 123" pero no pasó nada
Gobliins

2
@Gobliins que desee curl -X GET -H "Authorization: Bearer your_token", dónde your_tokenestá su token de portador. Por ejemplocurl -X GET -H "Accept: application/json" -H "Authorization: Bearer 00000000-0000-0000-0000-000000000000" "http://localhost/secure-endpoint"
Steve K

15
Desafortunadamente, esto no funciona bien con la interfaz de usuario de Swagger: hacer clic en "Autorizar" y proporcionar un token simple generará ejemplos de curl "Pruébelo" en -H "Authorization: foo"lugar de -H "Authorization: Bearer foo"como la respuesta de OpenAPI 3
Abe Voelker

56

Autenticación de portador en OpenAPI 3.0.0

OpenAPI 3.0 ahora admite la autenticación Bearer / JWT de forma nativa. Se define así:

openapi: 3.0.0
...

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

security:
  - bearerAuth: []

Esto es compatible con Swagger UI 3.4.0+ y Swagger Editor 3.1.12+ (nuevamente, ¡solo para especificaciones de OpenAPI 3.0!).

La interfaz de usuario mostrará el botón "Autorizar", en el que puede hacer clic e ingresar el token de portador (solo el token en sí, sin el prefijo "Bearer"). Después de eso, las solicitudes de "pruébalo" se enviarán con el Authorization: Bearer xxxxxxencabezado.

Agregar Authorizationencabezado mediante programación (Swagger UI 3.x)

Si usa la interfaz de usuario de Swagger y, por alguna razón, necesita agregar el Authorizationencabezado mediante programación en lugar de que los usuarios hagan clic en "Autorizar" e ingresen el token, puede usar el requestInterceptor. Esta solución es para Swagger UI 3.x ; UI 2.x utilizó una técnica diferente.

// index.html

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

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

1
¿Cómo implemento esto en la documentación de swagger generada por flask-restplus?
Chang Zhao

Dudo que la respuesta se alinee con la pregunta que se hizo.
Vishrant

16

Por qué funciona "Respuesta aceptada" ... pero no fue suficiente para mí

Esto funciona en la especificación. Al menos swagger-tools(versión 0.10.1) lo valida como válido.

Pero si está utilizando otras herramientas como swagger-codegen(versión 2.1.6) encontrará algunas dificultades, incluso si el cliente generado contiene la definición de Autenticación, como esta:

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

No hay forma de pasar el token al encabezado antes de que se llame al método (punto final). Mire en esta firma de función:

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

Esto significa que solo paso la devolución de llamada (en otros casos, parámetros de consulta, etc.) sin un token, lo que conduce a una compilación incorrecta de la solicitud al servidor.

Mi alternativa

Desafortunadamente, no es "bonito", pero funciona hasta que obtengo el soporte de JWT Tokens en Swagger.

Nota: que se está discutiendo en

Entonces, maneja la autenticación como un encabezado estándar. En el pathobjeto, agregue un parámetro de encabezado:

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'

Esto generará un cliente con un nuevo parámetro en la firma del método:

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

Para usar este método de la manera correcta, simplemente pase la "cadena completa"

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

Y funciona.


"el token viene de otra parte" ... Me interesa el otro lugar. ¿Qué ocurre cuando iniciaste sesión, te dirigieron a tu inicio de sesión y te redirigieron a tu api swagger, cómo puedes usar el token de acceso que recibiste?
Nadine

0

Publicando la respuesta 2020 en JSON usando 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

Mi forma de Hackie para resolver esto fue modificando el archivo swagger.go en el paquete echo-swagger en mi caso:

En la parte inferior del archivo, actualice la función window.onload para incluir un requestInterceptor que formatea correctamente el token.

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

}

Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.