Single Sign-On

El Single Sign-On (SSO) autentica al usuario en un proveedor de identidad corporativo habilitado en el entorno. El flujo ocurre en el navegador, mediante redirecciones y cookies.

El proveedor se identifica por el nombre registrado por el administrador del servicio (parámetro provider).

OAuth 2.0, OAuth 2.1 y OpenID Connect

En el inicio de sesión con OAuth 2.0 y OpenID Connect, la API usa PKCE (S256) y un state de un solo uso, como exige OAuth 2.1.

    sequenceDiagram
    participant U as Navegador
    participant A as Riversoft STCP DirectLink API
    participant P as Proveedor de identidad
    U->>A: GET /sso/login?provider=<nombre>
    A-->>U: Redirección al proveedor
    U->>P: Autenticación del usuario
    P-->>U: Redirección con state y code
    U->>A: GET o POST /sso/oauth2/cb
    A-->>U: Sesión establecida (cookie de sesión)
  

Iniciar sesión

Abra en el navegador la URL de inicio de sesión con el nombre del proveedor:

https://api.ejemplo.com/directlink/v2/sso/login?provider=proveedor-corporativo

Para inspeccionar la redirección:

curl -i --get \
  --data-urlencode 'provider=proveedor-corporativo' \
  "$API_BASE/sso/login"

Callback de autorización

Después de autenticar al usuario, el proveedor redirige el navegador a GET o POST /sso/oauth2/cb con state y code. El state debe corresponder al creado al inicio del flujo; no invente ni reutilice esos valores.

# Formato ilustrativo; en un inicio de sesión real, la llamada la realiza la redirección del proveedor.
curl -i --get \
  --data-urlencode 'state=<estado-proporcionado-en-el-flujo>' \
  --data-urlencode 'code=<codigo-de-autorizacion>' \
  "$API_BASE/sso/oauth2/cb"

Cierre de sesión federado

El cierre de sesión comienza en GET /sso/logout, con el provider y la sesión autenticada. La API dirige el navegador al proveedor o al destino de cierre de sesión:

curl -i -b cookies.txt -c cookies.txt --get \
  --data-urlencode 'provider=proveedor-corporativo' \
  "$API_BASE/sso/logout"

El proveedor completa el cierre de sesión llamando a GET o POST /sso/oauth2/logout/cb con state y provider:

# Formato ilustrativo.
curl -i --get \
  --data-urlencode 'state=<estado-proporcionado-en-el-flujo>' \
  --data-urlencode 'provider=proveedor-corporativo' \
  "$API_BASE/sso/oauth2/logout/cb"

SAML 2.0

    sequenceDiagram
    participant U as Navegador
    participant A as Riversoft STCP DirectLink API
    participant P as Proveedor SAML
    U->>A: GET /sso/login?provider=<nombre>
    A-->>U: Redirección al proveedor
    U->>P: Autenticación del usuario
    P-->>U: Formulario con SAMLResponse
    U->>A: POST /sso/saml2/acs
    A-->>U: Sesión establecida (cookie de sesión)
  

Obtener los metadatos

Para registrar la API en el proveedor SAML, obtenga los metadatos XML del proveedor configurado. Indique el proveedor en la query string o en la ruta:

curl -i --get \
  --data-urlencode 'provider=proveedor-saml' \
  "$API_BASE/sso/saml2/metadata"

curl -i "$API_BASE/sso/saml2/metadata/proveedor-saml"

Inicio de sesión

El inicio de sesión SAML comienza en GET /sso/login?provider=proveedor-saml. Después de la autenticación, el proveedor envía un formulario HTTP POST a /sso/saml2/acs con SAMLResponse y, cuando corresponde, RelayState:

# Formato ilustrativo; úselo solo en pruebas con valores de un flujo SAML válido.
curl -i -X POST "$API_BASE/sso/saml2/acs" \
  --data-urlencode 'SAMLResponse=<respuesta-saml-base64>' \
  --data-urlencode 'RelayState=<estado-opcional>'

Cierre de sesión

El cierre de sesión SAML usa el mismo inicio (GET /sso/logout?provider=proveedor-saml). El proveedor envía la respuesta de cierre de sesión a /sso/saml2/slo, mediante GET o POST:

# Formato ilustrativo.
curl -i -X POST "$API_BASE/sso/saml2/slo" \
  --data-urlencode 'SAMLResponse=<respuesta-logout-saml-base64>' \
  --data-urlencode 'RelayState=<estado-opcional>'

Referencia

Contratos completos en Referencia: Single Sign-On.