Single Sign-On
El Single Sign-On (SSO) autentica al operador en un proveedor de identidad corporativo registrado en el registro de la API (ssoProviders). El flujo ocurre en el navegador, mediante redirecciones, y termina con un token Bearer entregado al Riversoft Console Portal o a su aplicación.
Importante
Los retornos (/auth/api/v1/sso/saml2/acs y /auth/api/v1/sso/oauth2) los llama el proveedor de identidad durante el flujo. Su aplicación no debe simular esas llamadas.
sequenceDiagram
participant U as Navegador
participant A as Riversoft STCP Gemini API
participant P as Proveedor de identidad
U->>A: GET /auth/api/v1/sso/login?provider=<nombre>
A-->>U: 307 Redirección al proveedor
U->>P: Autenticación del operador
P-->>U: Retorno con SAMLResponse (SAML 2.0) o code (OAuth 2.0)
U->>A: POST /saml2/acs o GET /oauth2
A-->>U: 303 a sso_login_redirect?token=...&token_type=Bearer&scope=...
Listar los proveedores
GET /info/sso/providers lista los proveedores habilitados, sin exigir token:
curl -s "$API_BASE/info/sso/providers"[
{"Name": "EntraID", "Type": "oauth2"},
{"Name": "directorio-corporativo", "Type": "ldap"}
]Los proveedores saml2 y oauth2 usan el flujo de esta página. Los proveedores ldap usan el inicio de sesión con LDAP.
Iniciar sesión
Abra en el navegador la URL de inicio de sesión con el nombre del proveedor:
https://api.ejemplo.com:33070/auth/api/v1/sso/login?provider=EntraIDLa API responde 307 y envía el navegador al proveedor. Con un proveedor inexistente o de otro tipo, responde 400, en texto.
Retorno del proveedor
Después de autenticar al operador, el proveedor devuelve el navegador a la API:
| Protocolo | Retorno | Datos recibidos |
|---|---|---|
| SAML 2.0 | POST /auth/api/v1/sso/saml2/acs | SAMLResponse y RelayState |
| OAuth 2.0 / OpenID Connect | GET /auth/api/v1/sso/oauth2 | code y state |
Registre en el proveedor la dirección de retorno indicada en ssoRedirectUrlOrEndpoint, en el registro del proveedor (esquema SsoProvider de la Especificación OpenAPI).
La API valida la respuesta, identifica al operador por el nombre recibido del proveedor y redirige el navegador (303) a la dirección de sso_login_redirect, con el token en la query string:
https://console.ejemplo.com/?token=<access_token>&token_type=Bearer&scope=<permisos en JSON, codificados en Base64>| Parámetro | Descripción |
|---|---|
token | Token de acceso, usado como Bearer en las llamadas siguientes. |
token_type | Siempre Bearer. |
scope | Permisos del operador, en JSON codificado en Base64. |
En caso de falla, la redirección lleva el parámetro error, con el motivo.
Nota
El operador debe existir en Riversoft STCP Gemini API con el mismo nombre recibido del proveedor. En el inicio de sesión por SSO, no se aplica el 2FA de la API: los factores de autenticación son los que exige el proveedor de identidad.
Logout federado
El logout usa la ruta común, DELETE /disconnect/api/v3/logout. Con sso_logout_end_session habilitado, la respuesta trae en redirect la dirección de logout del proveedor; redirija el navegador a ella.
En SAML 2.0, el proveedor completa el logout llamando a POST /auth/api/v1/sso/saml2/slo, y la API redirige el navegador (303) al destino final.
Precaución
El token llega en la query string de la redirección. Léalo en cuanto cargue la página, elimínelo de la URL y no lo registre en logs.