Login local e 2FA

O login autentica o operador com um formulário OAuth 2.0 (password grant) e devolve um token Bearer. Quando a autenticação de dois fatores (2FA) está habilitada, a API pede um código TOTP antes de entregar o 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 desabilitada
        A-->>C: 200 OK + access_token
    else 2FA habilitada, TOTP cadastrado
        A-->>C: 200 OK + URL do desafio
        C->>A: POST URL do desafio (Code)
        A-->>C: 200 OK + access_token
    else 2FA habilitada, primeiro acesso
        A-->>C: 200 OK + URL do desafio + secret + qrcode
        Note over C: O operador cadastra a conta no aplicativo autenticador
        C->>A: POST URL do desafio (Code)
        A-->>C: 200 OK + access_token
    end
  

Fazer o login

Envie as credenciais do operador em um formulário application/x-www-form-urlencoded:

read -r -p 'Operador: ' API_USER
read -r -s -p 'Senha: ' 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"

O header Content-Type deve ser exatamente application/x-www-form-urlencoded, sem charset. Com outro valor, a API responde 415.

Login com LDAP

Para entrar com uma conta do diretório corporativo, informe o usuário no formato <provedor>/<operador>. O <provedor> é o nome do provedor LDAP cadastrado no cadastro da API (ssoProviders):

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

O operador precisa existir na Riversoft STCP Gemini API com o mesmo nome. O LDAP só é aceito em /oauth/v2/token.

Resposta sem 2FA

Quando a 2FA está desabilitada, a API responde 200 com o token:

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

Veja como usar o token em Sessão e logout.

Concluir a 2FA

A 2FA é habilitada no cadastro da API (API/Supervisão), no campo enable2FA, ou pela variável de ambiente DIRLMFA (veja os parâmetros da API). Com ela habilitada, o login responde 200 com o caminho do desafio, em vez do token. A resposta não tem campo status: o que indica a etapa são os campos presentes.

Responder o desafio

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

Envie o código TOTP de 6 dígitos em JSON, para o caminho recebido em URL:

export MFA_PATH='<URL recebida no login>'
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"

Com o código válido, a API responde 200 com o token, no mesmo formato da resposta sem 2FA. O campo Operator do corpo é opcional: a API usa o operador do desafio.

Cadastrar o TOTP (primeiro acesso)

No primeiro login com a 2FA habilitada, a API gera um segredo TOTP para o operador e o devolve junto com o caminho do desafio:

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

Para exibir o QR code, use o valor direto em uma URL data::

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

O cadastro segue estes passos:

1. Exiba o QR code e o segredo e peça ao operador 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 para o caminho recebido em URL, como em Responder o desafio.
3. Com o código válido, a API responde 200 com o token. O login está concluído; nos próximos logins, a resposta traz só a URL.

Erros

Os erros vêm em JSON, com error e error_description.

Próximos passos

• Usar o token nas rotas protegidas
• Referência de /oauth/v2/token