Autenticación
Guías relacionadas: Inicio de sesión local y 2FA, Password grant, Single Sign-On y Sesión y logout.
Los errores de las rutas de autenticación vienen en JSON, con error y error_description.
POST /oauth/token
Emite el token de acceso por OAuth 2.0 password grant, solo con la autenticación nativa. No aplica el 2FA y no acepta LDAP.
Acceso: público.
| Header | Valor |
|---|---|
Content-Type | application/x-www-form-urlencoded, exactamente así |
| Campo (formulario) | Tipo | Obligatorio | Descripción |
|---|---|---|---|
grant_type | string | Sí | Siempre password. |
username | string | Sí | Operador. |
password | string | Sí | Contraseña del operador. |
Respuesta 200
| Campo | Descripción |
|---|---|
access_token | Token de acceso para las llamadas siguientes. |
scope | Permisos del operador (JSON serializado como texto). |
operator | Operador autenticado. |
rest_name | Nombre del registro de la API. |
token_type | Bearer. |
Respuestas
| HTTP | Significado |
|---|---|
200 | Token emitido. |
400 | Parámetros ausentes (username, password), grant_type diferente de password o cuerpo vacío. |
401 | Credenciales no aceptadas u operador bloqueado después de exceder el límite de fallas de las políticas de contraseña. |
415 | Content-Type diferente de application/x-www-form-urlencoded. |
500 | Error interno. |
El token es válido durante 60 minutos de forma predeterminada, o durante el tiempo definido en session_duration en el config.json de la API (máximo de 720 minutos).
POST /oauth/token HTTP/1.1
Host: api.ejemplo.com:33070
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=<operador>&password=<contraseña>POST /oauth/v2/token
Primera etapa del inicio de sesión, con el 2FA y el LDAP. Recibe el mismo formulario de POST /oauth/token. Para LDAP, indique username en el formato <proveedor>/<operador>, con el nombre del proveedor LDAP registrado en ssoProviders.
Acceso: público.
| Situación | Respuesta 200 |
|---|---|
| 2FA deshabilitado | El token, en el mismo formato de POST /oauth/token. |
| 2FA habilitado, TOTP registrado | URL: ruta del desafío (/oauth/v2/token/mfa/{challengeID}). |
| 2FA habilitado, primer acceso | URL, secret (secreto TOTP en Base32) y qrcode (PNG de 200 × 200 en Base64 estándar). El secreto ya queda guardado. |
Las respuestas de error son las mismas de POST /oauth/token.
POST /oauth/v2/token/mfa/{challengeID}
Segunda etapa del inicio de sesión con 2FA. Envíe el código de 6 dígitos generado por la aplicación autenticadora.
Acceso: público.
| Header | Valor |
|---|---|
Content-Type | application/json, exactamente así |
| Campo (JSON) | Tipo | Obligatorio | Descripción |
|---|---|---|---|
Code | string | Sí | Código TOTP. |
Operator | string | No | Ignorado: la API usa el operador del desafío. |
Respuestas
| HTTP | Significado |
|---|---|
200 | Código válido. El cuerpo trae el token, en el mismo formato de POST /oauth/token. |
400 | Cuerpo vacío, JSON no válido o Content-Type diferente de application/json. |
401 | Código no válido (Invalid code), desafío inexistente (You need to authenticate first at /oauth/token) u operador bloqueado en el cuarto código incorrecto. |
500 | Error interno. |
POST /oauth/v2/token/mfa/<challengeID> HTTP/1.1
Host: api.ejemplo.com:33070
Content-Type: application/json
{"Code": "123456"}Single Sign-On
Rutas disponibles cuando hay proveedores SSO en el registro de la API. Son públicas y las usa el navegador.
| Método y ruta | Llamada por | Descripción |
|---|---|---|
GET /auth/api/v1/sso/login?provider=<nombre> | Navegador | Inicia el inicio de sesión. Responde 307 al proveedor (solo saml2 y oauth2), o 400 en texto con un proveedor no válido. |
POST /auth/api/v1/sso/saml2/acs | Proveedor SAML 2.0 | Recibe SAMLResponse y RelayState. |
GET /auth/api/v1/sso/oauth2 | Proveedor OAuth 2.0 | Recibe code y state. |
POST /auth/api/v1/sso/saml2/slo | Proveedor SAML 2.0 | Completa el logout federado y redirige (303) al destino final. |
Los retornos de inicio de sesión redirigen (303) a sso_login_redirect con token, token_type (Bearer) y scope (permisos en JSON codificado en Base64) en la query string. En caso de falla, con el parámetro error.
DELETE /disconnect/api/v3/logout
Cierra la sesión e invalida el token.
Acceso: Bearer.
| Header | Valor |
|---|---|
Authorization | Bearer <access_token> |
Accept | application/json |
Respuesta 200
| Campo | Tipo | Descripción |
|---|---|---|
data | string | Resultado de la operación (Logout successful). |
redirect | string | Dirección de logout en el proveedor de identidad. Presente solo con sso_logout_end_session habilitado y sesión SSO. |
Respuestas
| HTTP | Significado |
|---|---|
200 | Sesión cerrada. |
401 | Token ausente o no válido. |
500 | Error interno. |