Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

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.

ChaveTipoObrigatoriedadeValor
HOSTAUTHENTICATIONValor EspecíficoOpcional
  • 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 seriviço será autenticado.Parâmetros Específicos da Autenticação via Token (OAuth2/

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

Para o método Jwt, outros parâmetros são obrigatórios para a validação do token.

  • JWT
)
ChaveTipo
Valor
JWTALLOWEDSCOPESTextoOpcional

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

Jwt

JWT. Ex.: api1.write, api1.read

JWTAUDIENCETexto
Identifica o recurso protegido pelo Jwt
OpcionalDestinatário do token, representa a aplicação que irá usá-lo.
Ex.: api1
JWTCERTIFICATETHUMBPRINTTextoObrigatórioIdentifica o certificado utilizado para validar a assinatura do
Jwt
JWT
Ex.: D1AE26F90417AC68D13DC0C734F950541F0CCB36
JWTISSUERNAMETexto
Identifica o fornecedor do Jwt
Ex.:
OpcionalO nome da API/fornecedor do token (Caso não seja fornecido, a assinatura será feita como "totvs-rm-host").
Ex.: https://sts.totvs.com.br


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

Informações
Bloco de código
languagexml
<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)

  • JWTAUDIENCE

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

Informações
Bloco de código
languagexml
<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

Informações
Bloco de código
languagexml
<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.

Informações
Bloco de código
languagexml
<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 deve estar na pasta Pessoal da máquina local:

Image Added

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
iconfalse
Bloco de código
GET [HOST]:[PORT]/api/.well-known/security/jwks
Informações

Para mais informações acerca de Json Web Tokens (JWT) e toda a arquitetura, acesse: Json Web Tokens - jwt.io, RFC7519 - JSON Web Token (JWT), RFC7515 - JSON Web Signature (JWS), RFC7516 - JSON Web Encryption (JWE), RFC7517 - JSON Web Key (JWK)RFC7518 - JSON Web Algorithms (JWA)

Exemplos


Chamando endpoint via Postman

  1. Endpoint protegido sem autenticação:


  2. Endpoint protegido com HTTP Basic:


  3. Endpoint protegido com Bearer Token (JWT):

 


Informações
iconfalse
Informações
iconfalse

Produto: Framework

Informações
iconfalse

Versão: 12.1.19XXXX

Informações
iconfalse

Processo: Estrutura de segurança de serviços HTTP

Informações
iconfalse
titleÍndice

Índice
exclude.*ndice:
stylenone

Informações
iconfalse
Informações
iconfalse

Status: Em desenvolvimento

Informações
iconfalse

Data:20092017 

Informações
iconfalse

Autores:

Diogo Damiani Ferreira

Samuel Rener Santos Silva_