Segurança

A Riversoft® STCP Gemini API dá acesso à configuração, à administração e à supervisão do ambiente. Por isso, as credenciais de operador e os tokens devem ser protegidos como senhas de administração. Esta página reúne as boas práticas para quem integra com a API. Os recursos de segurança do produto (TLS, SSO, MFA e políticas de senha) estão em Segurança do Riversoft STCP Gemini.

Transporte

• Publique a API somente por HTTPS: habilite ssl no config.json da API, com um certificado válido. Veja Configuração da API.
• Use a opção -ns (sem TLS) somente em ambientes de teste isolados.
• Valide o certificado do servidor no cliente. Não desative a verificação (por exemplo, curl -k).
• Libere o acesso à porta da API somente para as redes e os sistemas que precisam dela.

Credenciais e tokens

• Não grave senhas, tokens ou segredos TOTP 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 60 minutos por padrão (session_duration, até 720 minutos); obtenha um novo token quando ele expirar.
• O token é assinado com o api_secret da API: use um valor forte, privado e exclusivo do ambiente.
• Não reutilize credenciais de produção em ambientes de teste.

Autenticação de dois fatores

• Habilite a 2FA dos operadores no cadastro da API (enable2FA). Com ela, use o login por POST /oauth/v2/token: a rota POST /oauth/token não aplica a 2FA. Veja Login local e 2FA.
• Exiba o segredo TOTP e o QR code somente para o próprio operador, e só no primeiro acesso.
• O desafio aceita três códigos errados; no quarto, o operador é bloqueado.
• Se o operador perder o aplicativo autenticador, redefina a 2FA dele pela manutenção. Um novo segredo é gerado no login seguinte.

Single Sign-On

• Os retornos de SAML 2.0 e OAuth 2.0 são enviados pelo provedor de identidade. Não monte códigos de autorização, state ou asserções SAML manualmente.
• No SSO, o token chega na query string do redirecionamento. Leia-o assim que a página carregar, remova-o da URL e não o registre em logs.
• No login por SSO, a 2FA é a exigida pelo provedor de identidade, e não a da API.

Veja Single Sign-On.

Sessão

• Mantenha o token em memória ou em armazenamento de sessão; não o grave em armazenamento permanente do navegador.
• Encerre a sessão com DELETE /disconnect/api/v3/logout quando a integração terminar. Depois de um login por SSO, redirecione o navegador para o endereço recebido em redirect, quando houver. Veja Sessão e logout.

Permissões

• Use um operador próprio para cada integração, em grupos com apenas as permissões necessárias (0 sem acesso, 1 leitura, 15 leitura e escrita).
• Limite, nas relações do grupo, as instâncias, os usuários e os operadores que a integração pode ver.
• O operador stcpadmin tem acesso total. Troque a senha padrão no primeiro acesso e não o use em integrações.

Veja Conceitos e arquitetura.

Dados sensíveis

• O CONFIG_TXT traz senhas e segredos das entidades. A API os devolve mascarados; não remova a máscara e não registre respostas completas em logs.
• Ao alterar uma entidade, reenvie o valor mascarado para manter o gravado. Envie um valor novo somente quando quiser trocá-lo.
• As credenciais de supervisão do cadastro da API e as credenciais dos bancos são dados sensíveis.
• A chave usada para criptografar essas senhas no banco é o api_secret, que deve ser igual nos demais módulos do ambiente. Veja Chave de criptografia das senhas.

Auditoria

Toda chamada feita por um operador é registrada com operador, método, caminho e status HTTP. Consulte o relatório de operadores e os relatórios de auditoria para acompanhar os acessos e as alterações.

Checklist de segurança

• API publicada somente por HTTPS, com validação de certificado.
• Credenciais e tokens fora do código e dos logs.
• api_secret forte e protegido.
• 2FA habilitada para os operadores, com login por POST /oauth/v2/token.
• Senha padrão do stcpadmin trocada, e o stcpadmin fora das integrações.
• Operador exclusivo e com permissões mínimas para cada integração.
• Token do SSO removido da URL depois de lido.
• Respostas com CONFIG_TXT fora dos logs.
• Logout ao final da sessão.
• Relatórios de operadores e de auditoria revisados periodicamente.