Objetivo

Este documento tem como objetivo auxiliar na configuração de segurança dos serviços HTTP (API's) expostos pelo Host.

Parâmetros

Os seguintes parâmetros podem ser utilizados no RM . Host.*. config a fim de configurar a segurança:

Tipo

Valor Específico

All (Default)

Basic

Jwt

Por padrão, os todos os métodos de autenticação são ativados. Portanto, independente do esquema utilizado (Basic ou Bearer), o serviço será autenticado.

Caso seja escolhido um método específico, os outros naturalmente apresentarão erro 401.

Parâmetros Específicos da Autenticação via Token (OAuth2/JWT)

o Host já possui padrões de segurança já pré-definidos, porém, caso seja de interesse do cliente, é possível personalizar as informações de segurança, conforme explícito abaixo.

Parâmetros

Para personalizar as informações de segurança de API's é necessário realizar alterações nos arquivos de configuração dos hosts correspondentes (Estes são os parâmetros  que devem ser incluídos no RM.Host.*.config para fazer uso de um certificado digital personalizado como assinatura do token JWT). Na tabela abaixo estão contidos os parâmetros de segurança que são possíveis de serem alterados e mais abaixo, a explicação de cada um destes parâmetros.

• HOSTAUTHENTICATION

O RM possibilita a autenticação de diversas formas pelas API's, conforme a documentação: Autorização / Autenticação em API's. Esta tag de configuração permite que o host aceite apenas um tipo de autenticação ao invés de todos suportados, que é o valor padrão da configuração. Caso seja escolhido um método específico, os outros naturalmente rejeitarão qualquer tentativa de autenticação, retornando o HTTP Error 401 - Unauthorized.

<add key="HOSTAUTHENTICATION" value="JWT"

Parâmetros Específicos da Autenticação via Token (OAuth2/JWT)

• JWTAUDIENCE
  

Este parâmetro é opcional, e irá determinar quais destinatários/aplicações irão utilizar o token.

<add key="JWTAUDIENCE" value="api1"

• JWTCERTIFICATETHUMBPRINT
  

Caso o objetivo seja utilizar um certificado digital personalizado para registro de tokens JWT, garantindo assim ainda mais segurança para sua aplicação (Vide Autorização / Autenticação em API's), este parâmetro é obrigatório, afinal ele receberá a assinatura (Thumbprint) do certificado personalizado salvo no servidor. Caso este parâmetro não seja fornecido, o RM irá registrar os tokens utilizando um certificado padrão embutido e assinado pelo próprio RM

<add key="JWTCERTIFICATETHUMBPRINT" value="D1AE26F90417AC68D13DC0C734F950541F0CCB36"

• JWTISSUERNAME
  

Este parâmetro recebe o fornecedor do certificado digital personalizado, caso este seja fornecido (Veja JWTCERTIFICATETHUMBPRINT). Este fornecedor será enviado no JWT e será utilizado por aplicações exteriores que façam uso da autenticação com o RM, como o TReports. Caso não seja fornecido, o fornecedor será enviado como "totvs-rm-host" automaticamente.

<add key="JWTISSUERNAME" value="https://sts.totvs.com.br"

O certificado para validação de tokens Jwt JWT deve estar na pasta Pessoal da máquina local:

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

Exemplos

Chamando endpoint via Postman

1. Endpoint protegido sem autenticação:
   
   
   
2. Endpoint protegido com HTTP Basic:
   
   
   
3. Endpoint protegido com Bearer Token (JWT):