Objetivo
Este documento tem como objetivo auxiliar na configuração de segurança dos serviços HTTP (API's) expostos pelo RM Host.
Parâmetros
. Por padrão, 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 (Os seguintes parâmetros podem ser utilizados no RM.Host.*.config a fim de configurar a segurança:). 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.
| Chave | Tipo | Obrigatoriedade | Valor |
|---|
| HOSTAUTHENTICATION | Valor Específico | Opcional | Basic Jwt |
Para o método Jwt, outros parâmetros são obrigatórios para a validação do token.
)Chave | Tipo | Valor |
| JWTALLOWEDSCOPES | Texto | Opcional | OBS.: Este parâmetro ainda não é relevante para a linha RM. Reservado para melhorias futuras. Indentificadores Identificadores dos recursos expostos via serviço e que devem estar presentes no JwtJWT. Ex.: api1.write, api1.read |
| JWTAUDIENCE | Texto | Opcional | Destinatário do token, representa a aplicação que irá usá-loIdentifica o recurso protegido pelo Jwt.
Ex.: api1 |
| JWTCERTIFICATETHUMBPRINT | Texto | Obrigatório | Identifica o certificado utilizado para validar a assinatura do JwtJWT
Ex.: D1AE26F90417AC68D13DC0C734F950541F0CCB36 |
| JWTISSUERNAME | Texto | Opcional | O nome da API/fornecedor do token (Caso não seja fornecido, a assinatura será feita como "totvs-rm-host").Identifica o fornecedor do Jwt
Ex.: https://sts.totvs.com.br |
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.
| Informações |
|---|
| Bloco de código |
|---|
| <add key="HOSTAUTHENTICATION" value="JWT" |
Na configuração acima, o host só aceitará chamadas que utilizem de bearer token em suas tentativas de autenticação. |
Parâmetros Específicos da Autenticação via Token (OAuth2/JWT)
Este parâmetro é opcional, e irá determinar quais destinatários/aplicações irão utilizar o token.
| Informações |
|---|
| Bloco de código |
|---|
| <add key="JWTAUDIENCE" value="api1" |
|
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
| Informações |
|---|
| Bloco de código |
|---|
| <add key="JWTCERTIFICATETHUMBPRINT" value="D1AE26F90417AC68D13DC0C734F950541F0CCB36" |
|
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.
| Informações |
|---|
| Bloco de código |
|---|
| <add key="JWTISSUERNAME" value="https://sts.totvs.com.br" |
|
| Dica |
|---|
| 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. Instruções mais detalhadas para implementação podem ser encontradas em Autorização / Autenticação em API's |
| Informações |
|---|
Abaixo o exemplo de uma configuração de certificado digital para JWT válida: Image Added |
O certificado para validação de tokens JWT validação de tokens 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:
| Informações |
|---|
|
| Bloco de código |
|---|
GET [HOST]:[PORT]/api/.well-known/security/jwks |
|
Exemplos
Chamando endpoint via Postman
- Endpoint protegido sem autenticação:
- Endpoint protegido com HTTP Basic:
- Endpoint protegido com Bearer Token (JWT):
