Segurança

A Riversoft® STCP DirectLink API dá acesso aos arquivos dos usuários. Por isso, as credenciais, os tokens e os links seguros devem ser protegidos como senhas. Esta página reúne as boas práticas para quem integra com a API. Os recursos de segurança do produto estão em Segurança do Riversoft STCP DirectLink.

Transporte

• Use HTTPS em produção e valide o certificado TLS do servidor. Não desative a verificação de certificado no cliente (por exemplo, curl -k).
• Acesse o serviço pelo host configurado no ambiente. Requisições com host ou porta diferentes podem ser recusadas.

Credenciais e tokens

• Não grave senhas, tokens, PINs, segredos TOTP ou links seguros no código-fonte, em arquivos versionados, no histórico do shell, em logs ou em chamados de suporte.
• Guarde as credenciais da integração em um cofre de segredos ou em variáveis de ambiente protegidas.
• Trate o access_token como uma senha. Ele vale pelo tempo indicado em expires_in; obtenha um novo token quando ele expirar.
• Não reutilize credenciais de produção em ambientes de teste.

Autenticação multifator

• O MFA do login local pode ser por PIN enviado por e-mail ou SMS, ou por código TOTP de aplicativo autenticador. Veja Login local e MFA.
• Exiba o segredo TOTP e o QR code somente para o próprio usuário, e só no cadastro.
• Os links de MFA são vinculados ao usuário e expiram. Não os altere nem os reutilize.

Single Sign-On

Os callbacks de OAuth 2.0 e SAML 2.0 são enviados pelo provedor de identidade. Não tente construir códigos de autorização, state ou asserções SAML manualmente: essas mensagens são assinadas e vinculadas à sessão e ao provedor configurados. Veja Single Sign-On.

Compatibilidade com OAuth 2.1

A API segue o OAuth 2.1 quando o password grant está desabilitado:

• os tokens são obtidos por token exchange ou pelo Single Sign-On e enviados somente no cabeçalho Authorization: Bearer;
• no Single Sign-On com OAuth 2.0 e OpenID Connect, a API usa PKCE (S256) e um state de uso único em cada login, como exige o OAuth 2.1.

O administrador do serviço escolhe os métodos de autenticação aceitos no serviço de rede da API, no Riversoft Console Portal. Se a sua integração usa o password grant, migre para o token exchange antes de desabilitá-lo. Veja Tokens OAuth.

Sessão

• O cookie __Host-dirl_session é emitido com os atributos Secure, HttpOnly e SameSite=Strict. Se a sua aplicação guardar o cookie (por exemplo, em cookies.txt com curl), proteja o arquivo como uma credencial e apague-o ao final da sessão.
• Encerre a sessão com /auth/logout (ou com o logout SSO) quando a integração terminar. Encerrar uma transferência não encerra a sessão. Veja Sessão e logout.

Permissões

• Use um usuário próprio para cada integração, com acesso somente às caixas postais necessárias.
• Use o token de impersonação somente em integrações técnicas, e guarde-o como uma credencial de longa duração. Veja Tokens OAuth.

Links seguros

• Encaminhe links de download apenas ao destinatário autorizado.
• Os links de download da listagem só funcionam com o token ou o cookie de sessão do próprio usuário. Para entregar um arquivo a terceiros, use o link compartilhado.
• Não registre links seguros em logs nem os inclua em mensagens públicas.
• Não altere nem reutilize links de MFA, de alteração de senha ou de download. Eles são vinculados à operação e expiram.
• Envie o PIN por um canal diferente daquele usado para o link, quando a sua aplicação fizer esse encaminhamento.
• Os prazos padrão são de 24 horas para links de download e 180 segundos para PINs; o administrador pode alterá-los. Planeje o encaminhamento para que o destinatário use o link dentro do prazo.

Integridade dos arquivos

No upload, informe o hash esperado do arquivo (campo h, SHA-256, no multipart; header X-STCPDIRECTLINK-HASH no corpo binário) para que o serviço possa validar o conteúdo recebido. Veja Enviar arquivos.

Auditoria

As transferências ficam registradas no log do Riversoft STCP DirectLink. Consulte o relatório de transferências para acompanhar os envios e os downloads da integração.

Checklist de segurança

• HTTPS com validação de certificado.
• Credenciais fora do código e dos logs.
• MFA habilitado para os usuários do login local.
• Usuário dedicado à integração, com permissões mínimas.
• Renovação do token antes ou após a expiração.
• Links seguros tratados como credenciais.
• Hash SHA-256 informado no upload, quando disponível.
• Logout ao final da sessão.
• Relatório de transferências revisado periodicamente.