Mudança na autenticação da API do SCADAFlex6
Olá! Este documento explica, em linguagem simples, uma mudança que vamos fazer em como sua aplicação se autentica na API do SCADAFlex6. Se seu sistema hoje chama nossa API — seja para consultar histórico de variáveis, enviar leituras, gerar relatórios ou qualquer outra integração — esta leitura é para você.
A boa notícia primeiro: o que muda é só a forma de conseguir e renovar o token de acesso. Tudo o que seu usuário já podia ver ou fazer continua exatamente igual.
- O que está mudando, em uma frase
Hoje, o próprio SCADAFlex6 confere sua senha e emite o token de acesso. A partir de agora, quem confere a senha e emite o token passa a ser o Keycloak — um sistema especializado só nisso, usado por milhares de empresas no mundo todo. O SCADAFlex6 continua igual em tudo o mais.
As duas responsabilidades que hoje moram juntas no SCADAFlex6 passam a ser divididas.
O que NÃO muda: As permissões continuam 100% no SCADAFlex6. Se seu usuário só enxergava 3 estações, continua só enxergando essas 3. Se ele não podia escrever em uma variável, continua não podendo. O Keycloak só responde “quem é essa pessoa” — quem decide “o que essa pessoa pode fazer” continua sendo o SCADAFlex6, do jeito que já é hoje. |
- Por que estamos fazendo essa mudança
- Token de renovação de verdade — hoje, se o token expira, a única forma de renovar é enviando usuário e senha de novo — não existe “renovação silenciosa”. Com o Keycloak, você recebe também um refresh token, que renova o acesso sem precisar reenviar a senha a cada vez.
- Mais segurança — centralizar a autenticação num único lugar reduz a superfície de risco e segue um padrão usado no mercado (OAuth2 / OpenID Connect), em vez de um mecanismo próprio mantido só por nós.
- Menos senha circulando — hoje sua senha de sistema precisa ser guardada por cada integração para poder relogar sozinha. Com o refresh token, isso deixa de ser necessário.
- Como funciona hoje
Sua aplicação manda usuário e senha direto para o SCADAFlex6, recebe um token, e usa esse token nas chamadas seguintes.
Fluxo atual: o SCADAFlex6 confere a senha e assina o token.
POST /api/Auth/Token Content-Type: application/json { “Username”: “seu.usuario”, “Password”: “sua-senha” } → resposta: { “access_token”: “…”, “expires_in”: 3600, … } |
- Como vai funcionar
Sua aplicação passa a pedir o token direto ao Keycloak — não mais ao SCADAFlex6. O restante (usar o token nas chamadas de API) continua igual: mesmo cabeçalho, mesmo formato.
Fluxo novo: o Keycloak confere a senha e assina o token; o SCADAFlex6 só valida.
POST https://<endereço-do-keycloak>/realms/<realm>/protocol/openid-connect/token Content-Type: application/x-www-form-urlencoded grant_type=password&client_id=<seu-client-id> &username=seu.usuario&password=sua-senha → resposta: { “access_token”: “…”, “refresh_token”: “…”, “expires_in”: 300, … } |
A partir daqui, nada muda: você continua anexando o token da mesma forma em toda chamada de API:
GET /api/v2/variables/{id}/history Authorization: Bearer <access_token> |
Quando o token expirar: hoje você reenvia usuário e senha. No novo fluxo, você troca o refresh_token por um access_token novo, sem precisar da senha de novo — mais rápido e mais seguro: |
POST https://<endereço-do-keycloak>/realms/<realm>/protocol/openid-connect/token grant_type=refresh_token&client_id=<seu-client-id> &refresh_token=<refresh_token recebido antes> |
- Passo a passo para adaptar sua integração
- Aguarde o cadastro do seu client — nossa equipe vai te enviar as credenciais do seu “client” no Keycloak (um identificador da sua aplicação — equivalente a um novo “usuário técnico” da integração).
- Troque a URL de login — aponte a chamada de login para o endereço do Keycloak em vez de /api/Auth/Token (endereço exato será informado junto das credenciais).
- Implemente a renovação via refresh_token — passe a guardar o refresh_token junto com o access_token, e use-o para renovar o acesso quando expirar, em vez de reenviar usuário e senha.
- Teste as chamadas normais de API — nenhuma chamada às APIs de negócio do SCADAFlex6 muda — nem endpoint, nem formato de resposta, nem permissão. Só a forma de obter o token é diferente.
- Valide em homologação — faça a troca num ambiente de testes antes de ir para produção. Vamos manter os dois fluxos funcionando lado a lado durante um período de transição.
- Perguntas frequentes
Vou perder acesso a alguma informação que já tinha?
Não. Permissões continuam decididas pelo SCADAFlex6, exatamente como hoje.
Preciso trocar a senha do meu usuário de integração?
Não necessariamente — o usuário existente é levado para o Keycloak. Qualquer ação necessária da sua parte será avisada com antecedência pela nossa equipe.
O formato das respostas da API muda?
Não. Só a forma de conseguir o token muda. Todas as demais chamadas — endpoints, payloads, paginação, filtros — continuam iguais.
E se minha integração não estiver pronta a tempo?
O fluxo atual (/api/Auth/Token) continuará disponível durante um período de transição, para dar tempo de todo mundo se adaptar sem quebrar nada de um dia para o outro. A data final de desligamento do fluxo antigo será comunicada com antecedência.
Preciso implementar uma tela de login no navegador?
Não, para integrações de sistema a sistema. Você continua enviando usuário e senha diretamente na chamada (agora para o Keycloak em vez do SCADAFlex6) — não é necessário nenhum redirecionamento de navegador.
- Dúvidas ou precisa de ajuda?
Fale com a nossa equipe técnica — estamos à disposição para apoiar a adaptação da sua integração, incluir sua aplicação como client no Keycloak e acompanhar os testes em homologação.