Autorização / Autenticação em API's

Introdução

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.

Indíce

Abaixo estão contidos os tipos de autenticação suportados pelas API's do RM:

Autenticação Bearer (Bearer Authentication)

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:

Token assinado pelo RM/TOTVS

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.

Token assinado por um certificado digital do cliente

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

• Para gerar um token assinado por um certificado digital do cliente, é necessário:
  

• 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.

Como utilizar

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:

1. Realize uma requisição POST ao endpoint http(s)://{dominio}:{porta}/api/connect/token/ via Postman, SoapUi, ou outro programa que realize requisições HTTP REST.
2. No corpo da requisição envie um JSON explicitando usuário e senha do RM para qual a autenticação está sendo direcionada:

• username
• password 

curl -X POST --location 'http://localhost:8051/api/connect/token' --header 'Content-Type: application/json' --data '{"grant_type": "password","username": "mestre","password": "totvs"}'

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.

Gerar Token Informando Alias

Na versão 2306, é possível gerar um token passando o "service_alias" no corpo da API "connect/token", evitando a necessidade de configurar completamente o subdomínio em alguns casos.

"service_alias" = informar o Alias que precisa para gerar o Token.

Abaixo segue a chamada para gerar um token utilizando um "Alias".

{
    "grant_type": "password",
    "username": "mestre",
    "password": "totvs",
    "servicealias":"CorporeRM"
}

Gerar Token Informando Alias com SubDomainMask 

Para gerar um token informando o "Alias" com o "subdomainMask" corretamente, é necessário que o valor do "serviceAlias" seja exatamente igual ao valor do "subdomainMask".

Por exemplo, se o domínio for "cliente1.site.com" e o valor do "serviceAlias" for "cliente1", o token será gerado corretamente.

O "serviceAlias" é o valor do "Alias" que está cadastrado no arquivo "Alias.dat".

Alias.dat

Caso o domínio seja diferente o token não é gerado.

Exemplo: cliente1.site.com diferente de serviceAlias que é cliente2

Duração do Token

A duração do token de acesso pode ser visualizada na resposta da API de geração de token. Sua duração padrão é de 5 minutos, e pode ser alterada, através da tag JWTTokenExpireMinutes, que pode ser inserida no RM.Host.exe.config, podendo ser configurada entre 1 e 43200 minutos (30 dias).

Já o refresh token tem a duração padrão de 16 horas, e também pode ser alterada, mas através da tag JWTRefreshTokenExpireMinutes, podendo ser configurada entre 1 e 129600 minutos (90 dias).

Renovação do Token

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:

Validação de JWT

Para confirmar que o token não foi adulterado durante a comunicação entre aplicações e o RM, é necessário validá-lo e para isso, é necessário possuir a chave pública responsável pela assinatura do JWT. Como a assinatura de tokens de segurança do RM funciona de forma assimétrica (Qualquer aplicação é capaz de validar o token recebido pelo RM, através de chaves públicas, porém apenas o RM é capaz de assinar um token de segurança, através de chaves privadas), a API de JWKS fornece a lista de JWK's possíveis para validação do token:

GET [HOST]:[PORT]/api/.well-known/security/jwks

Autenticação Basic

COMO UTILIZAR

Exemplo de utilização - Sucesso:

Realizando autenticação Basic no Postman: