Inicio de sesión local y MFA

El inicio de sesión local autentica al usuario con HTTP Basic y establece la sesión mediante cookie. Si el usuario tiene MFA habilitado, la API solicita un segundo factor antes de completar el inicio de sesión.

    sequenceDiagram
    participant C as Cliente
    participant A as Riversoft STCP DirectLink API
    C->>A: POST /auth/login (Authorization: Basic)
    alt status 0: sin MFA
        A-->>C: 200 OK + Set-Cookie __Host-dirl_session
    else status 1: PIN por correo electrónico o SMS
        A-->>C: 206 + linkURL (/auth/mfa)
        C->>A: POST linkURL (p=PIN)
        A-->>C: 200 OK + Set-Cookie
    else status 2: TOTP registrado
        A-->>C: 206 + linkURL (/auth/mfa)
        C->>A: POST linkURL (p=código TOTP)
        A-->>C: 200 OK + Set-Cookie
    else status 3: registro del TOTP
        A-->>C: 206 + linkURL (/auth/mfa/register) + secret + qrcode
        Note over C: El usuario registra la cuenta en la aplicación autenticadora
        C->>A: POST linkURL (p=código TOTP)
        A-->>C: 200 OK (registro concluido, sin sesión)
        C->>A: POST /auth/login (nuevo inicio de sesión)
        A-->>C: 206 status 2 (seguir el camino del TOTP registrado)
    end
  

Iniciar sesión

Envíe GET o POST a /auth/login con las credenciales en HTTP Basic. El endpoint no acepta otro tipo de credencial.

read -r -p 'Usuario: ' API_USER
read -r -s -p 'Contraseña: ' API_PASSWORD; printf '\n'

curl -i -c cookies.txt \
  --user "$API_USER:$API_PASSWORD" \
  -X POST \
  "$API_BASE/auth/login"

La opción -c cookies.txt guarda la cookie de sesión para las llamadas posteriores.

Cloudflare Turnstile

Cuando el administrador habilita la validación de Cloudflare Turnstile, /auth/login, /auth/forget y /auth/firstaccess exigen el token generado por el widget Turnstile en el header CF-Turnstile-Response. La API valida el token con Cloudflare antes de verificar las credenciales.

read -r -s -p 'Token Turnstile: ' TURNSTILE_TOKEN; printf '\n'

curl -i -c cookies.txt \
  --user "$API_USER:$API_PASSWORD" \
  -H "CF-Turnstile-Response: $TURNSTILE_TOKEN" \
  -X POST \
  "$API_BASE/auth/login"

El token es de un solo uso y caduca en 300 segundos: genere uno nuevo en cada intento. Con la validación deshabilitada, el header se ignora.

Respuesta sin MFA

Cuando el inicio de sesión no requiere MFA y las verificaciones de acceso se aprueban, la API responde 200 y envía la cookie segura __Host-dirl_session:

HTTP/1.1 200 OK
Set-Cookie: __Host-dirl_session=<token>; Path=/; Secure; HttpOnly; SameSite=Strict
Content-Type: application/json

{
  "status": 0,
  "description": "<descripción devuelta por la API>",
  "apiver": "v2 (9.0.1)",
  "user": "<usuario>",
  "urllink": "<enlace del portal>",
  "time": "<fecha y hora>"
}

El token de sesión se entrega solo en la cookie; no aparece en el JSON. Si su integración necesita un token Bearer, use el password grant.

Completar el MFA

Si el usuario tiene MFA, el inicio de sesión responde 206 Partial Content. El campo status indica la etapa que el frontend debe presentar:

El método viene de la configuración de la instancia (AuthMFAMethod: correo electrónico, SMS o aplicación autenticadora). El registro del usuario puede definir otro método o deshabilitar el MFA solo para él. El MFA se aplica al inicio de sesión local con HTTP Basic.

Responder el desafío (status 1 y 2)

{
  "status": 2,
  "description": "handlerAuthLogin:require MFA",
  "apiver": "v2 (9.0.1)",
  "user": "<usuario>",
  "linkURL": "<enlace seguro a /auth/mfa>",
  "secret": "",
  "qrcode": "",
  "time": "<fecha y hora>"
}

En el status 1, la respuesta no tiene los campos secret y qrcode, y la API envía el PIN al correo electrónico o al celular del usuario. En el status 2, los dos campos vienen vacíos.

Envíe el PIN o el código TOTP en el campo de formulario p a la URL completa recibida en linkURL:

export MFA_URL='<linkURL recibido en el inicio de sesión>'
read -r -s -p 'PIN o código TOTP: ' MFA_CODE; printf '\n'

curl -i -c cookies.txt -X POST \
  --data-urlencode "p=$MFA_CODE" \
  "$MFA_URL"

Con el código válido, la API completa el inicio de sesión: responde 200 con el mismo cuerpo de la respuesta sin MFA y envía la cookie de sesión.

Registrar el TOTP (status 3)

Cuando el método es la aplicación autenticadora y el usuario todavía no tiene TOTP registrado, la API genera un secreto nuevo y lo devuelve en la respuesta 206:

{
  "status": 3,
  "description": "handlerAuthLogin:require MFA",
  "apiver": "v2 (9.0.1)",
  "user": "<usuario>",
  "linkURL": "<enlace seguro a /auth/mfa/register>",
  "secret": "<secreto TOTP en Base32>",
  "qrcode": "<imagen PNG en Base64 URL-safe>",
  "time": "<fecha y hora>"
}

Para mostrar el código QR, conviértalo a Base64 estándar antes de armar la URL data::

const b64 = respuesta.qrcode.replace(/-/g, '+').replace(/_/g, '/');
imagen.src = `data:image/png;base64,${b64}`;

El registro sigue estos pasos:

1. Muestre el código QR y el secreto y pida al usuario que registre la cuenta en la aplicación autenticadora (Microsoft Authenticator, Google Authenticator u otra compatible con TOTP).

2. Pida el código de 6 dígitos generado por la aplicación y envíelo en el campo p al linkURL recibido:

   export MFA_REGISTER_URL='<linkURL de registro TOTP>'
   read -r -s -p 'Código TOTP: ' MFA_CODE; printf '\n'
   
   curl -i -X POST \
     --data-urlencode "p=$MFA_CODE" \
     "$MFA_REGISTER_URL"

3. Con el código válido, la API guarda el secreto y responde 200:

   {
     "status": 0,
     "description": "handlerAuthMfaRegister:succsessfully",
     "apiver": "v2 (9.0.1)",
     "user": "<usuario>",
     "length": 0,
     "time": "<fecha y hora>"
   }

4. Inicie sesión de nuevo en /auth/login. Ahora la respuesta es 206 con status 2: complete con el código de la aplicación, como en Responder el desafío.

Errores y validez

El enlace es válido durante el tiempo definido en secureLinkPinExpireSeconds, y el PIN enviado por correo electrónico o SMS tiene el tamaño de secureLinkPinMaxLen (vea la configuración de Riversoft STCP DirectLink).

Próximos pasos

• Usar la sesión en las rutas protegidas
• Referencia de /auth/login y /auth/mfa