Inicio de sesión local y 2FA

El inicio de sesión autentica al operador con un formulario OAuth 2.0 (password grant) y devuelve un token Bearer. Cuando la autenticación de dos factores (2FA) está habilitada, la API pide un código TOTP antes de entregar el token.

    sequenceDiagram
    participant C as Cliente
    participant A as Riversoft STCP Gemini API
    C->>A: POST /oauth/v2/token (grant_type, username, password)
    alt 2FA deshabilitado
        A-->>C: 200 OK + access_token
    else 2FA habilitado, TOTP registrado
        A-->>C: 200 OK + URL del desafío
        C->>A: POST URL del desafío (Code)
        A-->>C: 200 OK + access_token
    else 2FA habilitado, primer acceso
        A-->>C: 200 OK + URL del desafío + secret + qrcode
        Note over C: El operador registra la cuenta en la aplicación autenticadora
        C->>A: POST URL del desafío (Code)
        A-->>C: 200 OK + access_token
    end
  

Iniciar sesión

Envíe las credenciales del operador en un formulario application/x-www-form-urlencoded:

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

curl -s \
  --data-urlencode 'grant_type=password' \
  --data-urlencode "username=$API_USER" \
  --data-urlencode "password=$API_PASSWORD" \
  "$API_BASE/oauth/v2/token"

El header Content-Type debe ser exactamente application/x-www-form-urlencoded, sin charset. Con otro valor, la API responde 415.

Inicio de sesión con LDAP

Para iniciar sesión con una cuenta del directorio corporativo, indique el usuario en el formato <proveedor>/<operador>. El <proveedor> es el nombre del proveedor LDAP en el registro de la API (ssoProviders):

curl -s \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'username=directorio-corporativo/jperez' \
  --data-urlencode "password=$API_PASSWORD" \
  "$API_BASE/oauth/v2/token"

El operador debe existir en Riversoft STCP Gemini API con el mismo nombre. El LDAP solo se acepta en /oauth/v2/token.

Respuesta sin 2FA

Cuando el 2FA está deshabilitado, la API responde 200 con el token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "{\"stcpcore\":{\"instance\":15,\"user\":15,...}}",
  "operator": "stcpadmin",
  "rest_name": "RestAPI",
  "token_type": "Bearer"
}

Vea cómo usar el token en Sesión y logout.

Completar el 2FA

El 2FA se habilita en el registro de la API (API/Supervisión), en el campo enable2FA, o por la variable de entorno DIRLMFA (vea los parámetros de la API). Con él habilitado, el inicio de sesión responde 200 con la ruta del desafío, en lugar del token. La respuesta no tiene el campo status: lo que indica la etapa son los campos presentes.

Responder el desafío

{
  "URL": "/oauth/v2/token/mfa/01936b2e-7c4a-7d1e-9f3a-2b5c8d9e0f12"
}

Envíe el código TOTP de 6 dígitos en JSON a la ruta recibida en URL:

export MFA_PATH='<URL recibida en el inicio de sesión>'
read -r -s -p 'Código TOTP: ' MFA_CODE; printf '\n'

curl -s -X POST \
  -H 'Content-Type: application/json' \
  -d "{\"Code\": \"$MFA_CODE\"}" \
  "$API_BASE$MFA_PATH"

Con el código válido, la API responde 200 con el token, en el mismo formato de la respuesta sin 2FA. El campo Operator del cuerpo es opcional: la API usa el operador del desafío.

Registrar el TOTP (primer acceso)

En el primer inicio de sesión con el 2FA habilitado, la API genera un secreto TOTP para el operador y lo devuelve junto con la ruta del desafío:

{
  "URL": "/oauth/v2/token/mfa/01936b2e-7c4a-7d1e-9f3a-2b5c8d9e0f12",
  "secret": "<secreto TOTP en Base32>",
  "qrcode": "<imagen PNG en Base64>"
}

Para mostrar el código QR, use el valor directamente en una URL data::

imagen.src = `data:image/png;base64,${respuesta.qrcode}`;

El registro sigue estos pasos:

1. Muestre el código QR y el secreto y pida al operador 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 a la ruta recibida en URL, como en Responder el desafío.
3. Con el código válido, la API responde 200 con el token. El inicio de sesión está completo; en los próximos inicios de sesión, la respuesta trae solo la URL.

Errores

Los errores vienen en JSON, con error y error_description.

Próximos pasos

• Usar el token en las rutas protegidas
• Referencia de /oauth/v2/token