A maior parte das API's do RM exigem que seja realizada a autorização/autenticação para concluir a chamada, por razões de segurança. Neste documento, serão explicadas e definidas as possíveis formas de autenticação para consumo de API's do RM, suas vantagens e desvantagens e como utilizá-las.
Abaixo estão contidos os tipos de autenticação suportados pelas API's do RM:
Como definido pelo Swagger, uma Autenticação Bearer utiliza de tokens de segurança para realizar a autenticação entre servidor, que gera este token e client, que repassa esse token como prova de que está fazendo uma chamada confiável.
Autenticação Bearer (também chamada de Autenticação com token) é um Esquema de autenticação HTTP que envolve tokens de segurança chamados de bearer tokens. O nome Bearer Authentication ou Autenticação Bearer vem do inglês e pode ser entendido como "Permita o acesso ao portador deste token" O bearer token é uma informação textual encriptada, normalmente gerado pelo servidor em resposta à uma solicitação de login.
Para mais informações, acesse: Bearer Authentication - Swagger
Dentro do RM, é possível gerar um token, em formato JWT (Json Web Token) que será utilizado como token de autorização nas API's do sistema. Existem duas formas de se gerar este token, que iremos explicar agora:
Todos os tokens são gerados em server-side, pelo Host do RM |
Por padrão, o RM realiza a geração e assinatura de um token utilizando as credenciais padrões embutidas no sistema, não necessitando, apesar de recomendado, de ser incluído um certificado válido manualmente.
Por padrão, o RM certifica e valida um token padrão do sistema porém, para um nível maior de segurança, é recomendada a implementação de um certificado confiável próprio para validação, |
O RM também permite que seja inserido um certificado próprio do cliente, certificado este possuído apenas por ele e assim, mais seguro do que o padrão. Para realizar a configuração deste certificado dentro do RM, siga os passos abaixo:
INSTALAÇÃO DE CERTIFICADO
Antes de realizar a configuração de um certificado digital para geração de tokens no RM, é necessário instalar o certificado no servidor da aplicação. Para realizar essa instalação, siga a documentação: Habilitar SSL/TLS no Host
Apesar de a documentação de instalação de certificados seguir os passos para um certificado de SSL, os passos são os mesmos mas lembre-se de validar se o certificado digital utilizado suporta a assinatura de tokens |
CONFIGURAÇÃO
• Um certificado válido (Conforme passo anterior).
• Acrescentar no arquivo de configuração do Host (RM.Host.exe.config | RM.Host.Service.exe.config) as seguintes informações:
• Tag JWTCERTIFICATETHUMBPRINT (Obrigatório): Este é o thumbprint do certificado. Para conseguir este thumbprint, siga o passo 7 da documentação de instalação do certificado (Habilitar SSL/TLS no Host)
• Tag JWTISSUERNAME (Opcional): O nome da API que gerou o Token (Caso não seja fornecido, a assinatura será feita como "totvs-rm-host").
• Tag JWTAUDIENCE (Opcional): Destinatário do token, representa a aplicação que irá usá-lo.
Abaixo estão as instruções de como buscar um bearer token, tanto com base em um certificado embutido automaticamente na aplicação quanto um inserido manualmente.
Exemplo de utilização - Sucesso:
• username
• password
A requisição deve parecer com a abaixo
O token de segurança será gerado e já poderá ser utilizado no cabeçalho das requisições subsequentes às API's disponibilizadas pela TOTVS.
Exemplo de Token de Segurança gerado com sucesso e pronto para ser utilizado:
Utilize o token gerado incluindo-o no cabeçalho da requisição através da diretiva:
• Authorization: Bearer {token}
Inclusão do token no cabeçalho da requisição:
Após a inclusão do cabeçalho de autorização, realize uma requisição HTTP em uma das API's disponibilizadas pela TOTVS e verifique o resultado.
Requisição realizada na API de Usuário utilizando o token gerado:
Verifique que a requisição foi realizada com sucesso e os dados foram apresentados corretamente.
|
Exemplo de utilização - Sucesso:
Realize uma requisição http ao endpoint http(s)://{dominio}:{porta}/api/connect/token/ via Postman, SoapUi, ou outro programa que realize requisições http rest.
Na requisição deve-se utilizar o método POST.
No corpo da requisição utilize no body:
• refresh_token
• grant_type
Token de Segurança gerado com sucesso e pronto para ser utilizado:
A autenticação do tipo Basic não é recomendada pelo seu baixo nível de segurança. Sempre que possível, opte pela autenticação Bearer explicada acima |
COMO UTILIZAR
Exemplo de utilização - Sucesso:
Realizando autenticação Basic no Postman:
|
