Este documento é de uso interno e tem como objetivo detalhar o fluxo de autenticação das requisições entre o ERP e o TSS.
A partir do Release 12.1.33, o TSS terá a funcionalidade de utilização de Token de autenticação baseado em credenciais, contemplando a LGPD (Lei Geral de Proteção de Dados).
Para o fluxo de autenticação, serão utilizadas as credenciais (client_id e client_secret) geradas pelo TSS.
Através do TSSInterface ou TSSMonitor, foi desenvolvida a rotina de Configurações/Credenciais, onde somente o usuário ADMIN terá permissão para realizar o gerenciamento dessas credenciais.
Essas credenciais deverão ser informadas no ERP para que sejam utilizadas na requisição de solicitação do Token de autenticação da empresa, para isso foi desenvolvido o método TOKEN do webservice TSSAUTHENTICATION, que é responsável pela geração e atualização do Token de autenticação da empresa.
Esse Token de autenticação, deverá ser inserido no cabeçalho de todas as requisições enviadas para o TSS, para que seja realizada a autenticação segura no consumo do serviço.
Resumidamente, o TSS fornecerá as credenciais que deverão ser importadas no ERP. Com essas credenciais, o ERP deverá controlar a geração do Token de autenticação, e consequentemente, enviar no cabeçalho de todas requisições para o TSS.
1 - Concepção do produto TSS
Atualmente o TSS trabalha com entidades que são as empresas/filiais do ERP, assim eles são os atores principais do produto. Não foi concebido por uma gestão de usuário, ou seja, não realizamos o vínculo dos usuários cadastros do ERP com as entidades no TSS.
2 - Não existe um serviço centralizado de validação de usuário
O TSS também não possui um serviço que realize essa validação de usuário, como existe nas plataformas web atuais. Devido o TSS ser instalado em cliente On Premise, não conseguimos centralizar um serviço para que validassem os usuários, e consequentemente, consumissem a geração de Token de autenticação, e se ainda existisse, precisaríamos realizar o cadastro de todos os usuários de todos os clientes que utilizam TSS para realizar a validação, seria inviável para cada usuário cadastrado no ERP do cliente ser cadastrado também nesse serviço.
3 - Porque utilizar credenciais
Primeiramente, pensamos em colocar a geração dos dados para a autenticação no ERP, para que fosse o responsável por fornece-los, porém não conseguimos garantir que os dados que estão sendo enviados para o TSS são exatamente da empresa. Concluímos que para autenticação, o TSS terá que gerenciar esses dados de autenticação, ou seja, as credenciais.
A criação do Token é baseado no JSON Web Token (JWT), onde sua estrutura é um objeto Json composto por: Header, Payload e a Signature, ambos em base64url.
O JWT é um método RCT 7519 padrão da indústria para realizar autenticação entre duas partes por meio de um Token assinado que autentica uma requisição web. Esse Token é um código em Base64 que armazena objetos JSON com os dados que permitem a autenticação da requisição.
Um JSON Web Token é composto por três componentes básicos:
Header: É o cabeçalho do Token e contém dois campos:
alg: que informa o algoritmo usado para criar a hash da assinatura;
typ: que indica que este se trata de um Token JWT.
Exemplo:
{
"alg":"HS256",
"typ":"JWT"
}
Payload: É o componente onde se encontram os dados referentes à própria autenticação. Esses dados são definidos como Claims da entidade tratada. Existem 3 tipos de claims:
Reserved claims: atributos não obrigatórios (mas recomendados) que são usados na validação do Token pelos protocolos de segurança das APIs.
Public claims: atributos que usamos em nossas aplicações. Normalmente armazenamos as informações do usuário autenticado na aplicação.
Private claims: atributos definidos especialmente para compartilhar informações entre aplicações.
Exemplo:
{
"iss":"TOTVS-ADVPL-FWJWT",
"sub":"Administrador",
"iat":1605214516,
"userid":"000000",
"exp":1605218116,
"envId":"TSS12"
}
Signature: É a assinatura única de cada Token que é gerada a partir de um algoritmo de criptografia e tem seu corpo com base no header, no payload e no segredo definido pela aplicação.
Exemplo:
funcaoencode( encode64url(header) + "." + encode64url(payload), secret )
A concatenação das 3 partes separado por "." resulta no Token geração.
Vamos demonstrar o fluxo da autenticação que deverá ser realizado para consumir os métodos do TSS, por exemplo, o método CFGMODALIDADE do webservice SPEDCFGNFE.
Obs.: Foi utilizado a ferramenta SoapUi nos testes.
1 - Vamos criar o Token de autenticação com as credencias fornecidas pelo TSS e cadastradas no ERP , para isso, vamos consumir o método TOKEN do webservice TSSAUTHENTICATION.
2 - Precisamos criar a entidade que será representada pela empresa para realizar a configuração da modalidade, para isso, vamos consumir o método ADMEMPRESAS do webservice SPEDADM.
Note que foi criada a entidade 000001, e no cabeçalho foi enviado o Token de autenticação gerado anteriormente.
3 - Por fim, vamos configurar a modalidade do documento eletrônico NF-e (modelo 55) para Normal, para isso, vamos consumir o método CFGMODALIDADE do webservice SPEDCFGNFE.
Note que foi informado o Token de autenticação no cabeçalho da requisição, como também, a entidade criada anteriormente.
Para todos os métodos que estão validando o Token de autenticação, serão apresentadas possíveis mensagens de soapfault: Você não tem permissão para acessar esse servidor. Seu TSS está configurado com autenticação baseado em credenciais. Verifique se seu ERP está configurado corretamente com as credenciais fornecidas pelo seu TSS. Release TSS: 12.1.XXX | 3.0 Mensagem: XXXXXXX Composto por:
Exemplo de Soapfault de autenticação em uma requisição: |
Para a utilização do Token de autenticação do TSS, basta realizar a instalação do TSS 12.1.33.
Somente o usuário ADMIN do TSS terá permissão para realizar a gestão das credenciais.
Para gerenciar as credenciais, basta seguir as orientações do link: TSS0063_Configurando_TSS_com_autenticação#gerenciamento.
É recomendado utilizar o protocolo HTTPS para segurança nas requisições.
Para configurar, basta seguir as orientações do link: TSS0062_Configurando_TSS_com_protocolo_HTTPS.
<!-- esconder o menu --> <style> .ia-fixed-sidebar, .ia-splitter-left { display: sidebar; } #main { padding-left: 43px; padding-right: 10px; overflow-x: visible; } </style> |