¡Pruébalo! permite a los desarrolladores autenticar sus solicitudes directamente en la consola, usando el esquema de seguridad que defina tu API. Document360 lee la configuración de autenticación de tu especificación OpenAPI y muestra los campos correctos para cada método, de modo que los desarrolladores pueden proporcionar credenciales y enviar una solicitud autorizada sin dejar la documentación.
Este artículo explica cómo elegir un método de autenticación en la consola, cómo funciona cada método compatible y cómo configurar tu especificación OpenAPI para que el método aparezca correctamente en Pruébalo!. Para una visión general de la consola, consulta Probar endpoints con Pruébalo.
Elección de un método de autenticación
Cuando un endpoint define uno o más esquemas de seguridad, la consola Pruébalo! muestra una pestaña de Autorización . En la parte superior de esa pestaña hay un selector de métodos de Autenticación que lista todos los esquemas que soporta el endpoint.
Selecciona un método y la consola muestra los campos de credenciales para ese esquema. Si un endpoint soporta más de un método, los desarrolladores pueden elegir el que quieran usar para autenticarse.
Document360 soporta los siguientes métodos de autenticación:
| Método | Cómo funciona |
|---|---|
| Clave API | Una clave única pasaba en las cabeceras de las solicitudes. |
| Autenticación básica | Un nombre de usuario y una contraseña pasaban en la cabecera de la solicitud. |
| Ficha portadora | Un token generado tras iniciar sesión pasaba en la cabecera de Autorización. |
| OAuth 2.0 | Autorización delegada mediante un flujo de inicio de sesión, con soporte para PKCE. |
| OpenID Connect | Extiende OAuth 2.0 para añadir la verificación de identidad de usuario. |
Los métodos de autenticación se definen en tu especificación OpenAPI bajo components/securitySchemes y se aplican a puntos finales individuales usando el security campo.
Try It! soporta múltiples esquemas de seguridad simultáneamente, por lo que los desarrolladores pueden probar endpoints que requieren más de un método de autenticación dentro de la misma sesión.
Clave API
La autenticación de clave API utiliza una clave única que se pasa en las cabeceras de la solicitud.
En tu especificación de OpenAPI:
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
Aplícalo a un punto final:
/your-endpoint:
get:
security:
- ApiKeyAuth: []
En la consola, selecciona la clave API como método de autenticación. El campo Nombre está fijado al nombre del encabezado definido en tu especificación (X-API-Key en el ejemplo anterior), y los desarrolladores introducen su clave en el campo Valor . La clave se envía entonces en ese encabezado junto con la solicitud.
Autenticación básica
La autenticación básica requiere que se codifiquen y se transmitan un nombre de usuario y una contraseña en la Authorization cabecera de cada solicitud.
En tu especificación de OpenAPI:
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
Aplícalo a un punto final:
/your-endpoint:
get:
security:
- basicAuth: []
En la consola, selecciona Autenticación básica e introduce el nombre de usuario y la contraseña. ¡Pruébalo!, los codifica y los envía en la Authorization cabecera cuando se envía la solicitud.
Ficha portadora
La autenticación de token portador utiliza un token pasado en la Authorization cabecera como Bearer <token>.
En tu especificación de OpenAPI:
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
Document360 requiere que el esquema de seguridad sea nombrado BearerAuth (sensible a mayúsculas y minúsculas). Si esta definición falta en tu especificación, hacer clic en Pruébalo! en un endpoint afectado devolverá un error 403. Durante la importación, Document360 marcará esto en la sección de Alertas si detecta una definición faltante de BearerAuth.
Aplícalo a un punto final:
/your-endpoint:
get:
security:
- BearerAuth: []
En la consola, selecciona Token de portador e introduce el token. ¡Pruébalo! lo envía en el Authorization encabezado como Bearer <token>.
OAuth 2.0
OAuth 2.0 permite a los desarrolladores autorizar mediante un flujo de inicio de sesión en lugar de introducir una credencial estática. Document360 soporta los siguientes flujos — usa el que coincida con la forma en que tu API emite los tokens de acceso.
| Flujo | Cuándo usarlo |
|---|---|
| Código de autorización | Aplicaciones del lado del servidor donde el secreto del cliente puede mantenerse confidencial. |
| PKCE | Clientes públicos como aplicaciones de página única y aplicaciones móviles donde el secreto no puede mantenerse confidencial. |
| Credenciales de los clientes | Comunicación máquina a máquina donde no hay ningún usuario involucrado. |
| Implícito | Flujo de legado. No se recomienda para nuevas implementaciones. |
Inicio de sesión
Cuando un desarrollador selecciona OAuth 2.0 en la consola, ve la configuración del esquema y una lista de ámbitos, seguida de un botón de Autorizar . Los ámbitos definidos para el esquema están preseleccionados; Los desarrolladores pueden eliminar los que no necesiten antes de autorizar.
Al hacer clic en Autorizar inicia el flujo de inicio de sesión. Cuando la API utiliza PKCE, no se necesita configuración manual en la consola — Try It! gestiona el intercambio automáticamente, y el desarrollador solo necesita iniciar sesión. Una vez completada la autorización, la consola utiliza el token de acceso resultante para las solicitudes a ese punto final.
Definición de especificación de ejemplo (Flujo de código de autorización)
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
Para conocer el comportamiento de redirección del URI y la actualización de tokens que requiere OAuth 2.0, consulta Configuración de tu proveedor OAuth más abajo.
OpenID Connect
OpenID Connect amplía OAuth 2.0 añadiendo la verificación de identidad del usuario. Está configurado de forma similar a OAuth 2.0 y tiene los mismos requisitos de URI de redirección y renovación silenciosa.
En tu especificación de OpenAPI:
components:
securitySchemes:
openIdConnect:
type: openIdConnect
openIdConnectUrl: https://auth.yourdomain.com/.well-known/openid-configuration
En la consola, selecciona OpenID Connect y completa el flujo de inicio de sesión. Como con OAuth 2.0, consulta Configuración de tu proveedor OAuth más abajo para conocer la configuración requerida del proveedor.
Configuración de tu proveedor OAuth
Tanto OAuth 2.0 como OpenID Connect requieren dos ajustes para que la autorización funcione correctamente en Try It!.
URI de redirección — Una vez que un desarrollador completa el flujo de autorización, el proveedor lo redirige de nuevo a la referencia de la API. Añade la URL de callback OAuth de la referencia de API a la lista de URIs de redirección permitidos de tu proveedor OAuth:
https://<your-knowledge-base-domain>/assets/apidocs-oauth-callback.html
Sustituye <your-knowledge-base-domain> por el dominio en el que se publica la documentación de tu API.
Renovación silenciosa — Document360 actualiza automáticamente el token de acceso en segundo plano mientras un desarrollador está usando activamente Try It!, para que la sesión no expire a mitad de uso. No se requiere ninguna configuración por tu parte; Esto se gestiona automáticamente.
Aplicar múltiples esquemas de seguridad a un mismo punto final
Si un endpoint requiere más de un método de autenticación simultáneamente, defíneos juntos bajo security el nivel de operación:
/secure-endpoint:
get:
security:
- BearerAuth: []
ApiKeyAuth: []
Esto requiere que se proporcione tanto un token portador como una clave API antes de que se pueda enviar la solicitud. Try It! soporta múltiples esquemas de seguridad en una sola sesión, por lo que los desarrolladores pueden proporcionar credenciales para cada uno y enviar una solicitud autorizada.
Sesiones y seguridad
- Las credenciales son solo para sesión. Las credenciales que introduce un desarrollador se conservan solo para la sesión activa y no se guardan. Cuando termina la sesión, deben ser inscritos de nuevo.
- Las credenciales se ocultan en la vista previa de la solicitud. Los valores sensibles están ocultos en la vista previa de la Solicitud para que no se expongan en pantalla mientras se crea una petición.
Preguntas frecuentes
¿Dónde introducen los desarrolladores las credenciales en la consola?
En la pestaña de Autorización de la consola Pruébalo. Selecciona el método de autenticación y la consola muestra los campos de credenciales para ese esquema.
¿Por qué un endpoint devuelve un error 403 cuando hago clic en Pruébalo?
Para la autenticación de token al portador, Document360 requiere que el esquema de seguridad sea nombrado BearerAuth (sensible a mayúsculas y mayúsculas). Si esta definición falta en tu especificación, los extremos afectados devolven un error 403.
¿Necesito configurar algo para OAuth 2.0 con PKCE?
Cuando tu API utiliza PKCE, no se necesita una configuración manual en la consola: los desarrolladores solo tienen que hacer clic en Autorizar e iniciar sesión. Aún tienes que añadir el URI de redirección de la referencia de API a la lista de permitidos de tu proveedor OAuth. Consulta Configuración de tu proveedor OAuth.
¿Se guardan las credenciales que introduzca para la próxima vez?
No. Las credenciales se mantienen solo para la sesión activa y no se conservan. También están enmascarados en la vista previa de solicitudes para seguridad.