Login local e MFA

O login local autentica o usuário com HTTP Basic e estabelece a sessão por cookie. Se o usuário tiver MFA habilitado, a API pede um segundo fator antes de concluir o login.

    sequenceDiagram
    participant C as Cliente
    participant A as Riversoft STCP DirectLink API
    C->>A: POST /auth/login (Authorization: Basic)
    alt status 0: sem MFA
        A-->>C: 200 OK + Set-Cookie __Host-dirl_session
    else status 1: PIN por e-mail ou SMS
        A-->>C: 206 + linkURL (/auth/mfa)
        C->>A: POST linkURL (p=PIN)
        A-->>C: 200 OK + Set-Cookie
    else status 2: TOTP cadastrado
        A-->>C: 206 + linkURL (/auth/mfa)
        C->>A: POST linkURL (p=código TOTP)
        A-->>C: 200 OK + Set-Cookie
    else status 3: cadastro do TOTP
        A-->>C: 206 + linkURL (/auth/mfa/register) + secret + qrcode
        Note over C: O usuário cadastra a conta no aplicativo autenticador
        C->>A: POST linkURL (p=código TOTP)
        A-->>C: 200 OK (cadastro concluído, sem sessão)
        C->>A: POST /auth/login (novo login)
        A-->>C: 206 status 2 (seguir o caminho do TOTP cadastrado)
    end
  

Fazer o login

Envie GET ou POST para /auth/login com as credenciais em HTTP Basic. O endpoint não aceita outro tipo de credencial.

read -r -p 'Usuário: ' API_USER
read -r -s -p 'Senha: ' API_PASSWORD; printf '\n'

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

A opção -c cookies.txt guarda o cookie de sessão para as chamadas seguintes.

Cloudflare Turnstile

Quando o administrador habilita a validação Cloudflare Turnstile, /auth/login, /auth/forget e /auth/firstaccess exigem o token gerado pelo widget Turnstile no header CF-Turnstile-Response. A API valida o token na Cloudflare antes de verificar as credenciais.

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"

O token é de uso único e expira em 300 segundos: gere um novo a cada tentativa. Com a validação desabilitada, o header é ignorado.

Resposta sem MFA

Quando o login não exige MFA e as verificações de acesso são aprovadas, a API responde 200 e envia o cookie seguro __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": "<descrição retornada pela API>",
  "apiver": "v2 (9.0.1)",
  "user": "<usuario>",
  "urllink": "<link do portal>",
  "time": "<data e hora>"
}

O token de sessão é entregue somente no cookie; ele não aparece no JSON. Se a sua integração precisa de um token Bearer, use o password grant.

Concluir o MFA

Se o usuário tiver MFA, o login responde 206 Partial Content. O campo status indica a etapa que o frontend deve apresentar:

O método vem da configuração da instância (AuthMFAMethod: e-mail, SMS ou aplicativo autenticador). O cadastro do usuário pode definir outro método ou desabilitar o MFA só para ele. O MFA vale para o login local com HTTP Basic.

Responder o desafio (status 1 e 2)

{
  "status": 2,
  "description": "handlerAuthLogin:require MFA",
  "apiver": "v2 (9.0.1)",
  "user": "<usuario>",
  "linkURL": "<link seguro para /auth/mfa>",
  "secret": "",
  "qrcode": "",
  "time": "<data e hora>"
}

No status 1, a resposta não tem os campos secret e qrcode, e a API envia o PIN ao e-mail ou ao celular do usuário. No status 2, os dois campos vêm vazios.

Envie o PIN ou o código TOTP no campo de formulário p, para a URL integral recebida em linkURL:

export MFA_URL='<linkURL recebido no login>'
read -r -s -p 'PIN ou código TOTP: ' MFA_CODE; printf '\n'

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

Com o código válido, a API conclui o login: responde 200 com o mesmo corpo da resposta sem MFA e envia o cookie de sessão.

Cadastrar o TOTP (status 3)

Quando o método é o aplicativo autenticador e o usuário ainda não tem TOTP cadastrado, a API gera um segredo novo e o devolve na resposta 206:

{
  "status": 3,
  "description": "handlerAuthLogin:require MFA",
  "apiver": "v2 (9.0.1)",
  "user": "<usuario>",
  "linkURL": "<link seguro para /auth/mfa/register>",
  "secret": "<segredo TOTP em Base32>",
  "qrcode": "<imagem PNG em Base64 URL-safe>",
  "time": "<data e hora>"
}

Para exibir o QR code, converta para Base64 padrão antes de montar a URL data::

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

O cadastro segue estes passos:

1. Exiba o QR code e o segredo e peça ao usuário que cadastre a conta no aplicativo autenticador (Microsoft Authenticator, Google Authenticator ou outro compatível com TOTP).

2. Peça o código de 6 dígitos gerado pelo aplicativo e envie-o no campo p, para o linkURL recebido:

   export MFA_REGISTER_URL='<linkURL de cadastro 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. Com o código válido, a API grava o segredo e responde 200:

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

4. Faça o login de novo em /auth/login. Agora a resposta é 206 com status 2: conclua com o código do aplicativo, como em Responder o desafio.

Erros e validade

O link vale o tempo definido em secureLinkPinExpireSeconds, e o PIN enviado por e-mail ou SMS tem o tamanho de secureLinkPinMaxLen (veja a configuração do Riversoft STCP DirectLink).

Próximos passos

• Usar a sessão nas rotas protegidas
• Referência de /auth/login e /auth/mfa