Histórico da Página

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.

...

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:

...

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

...

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

...

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"
}

Image Added

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

Image Added

Alias.dat
Image Added

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

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

Image Added

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:

...

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

...

...