Escopos de autorização

Escopos de autorização definem privilégios no uso de APIs do sistema. Eles são definidos pelos desenvolvedores do sistema e são atribuídos aos usuários pelo administrador. Eles controlam os privilégios dos usuários no uso das APIs do sistema de uma forma similar ao controle de Permissões no acesso aos dados, processos e relatórios.

Eles normalmente são criados para controlar o uso de uma API específica do sistema, mas eles também podem ser utilizados para restringir privilégios mais amplos, que envolvam mais de uma API ou processo, como a permissão de atualizar o sistema, de executar um determinado script ou a de reiniciar um Engine remotamente.

A autenticação de um usuário pode ser feita no sistema por meio de suas credenciais de acesso, nome do usuário e senha, ou por meio de um token de autorização. Quando utilizadas as credenciais de acesso, a sessão autenticada terá acesso a todos os escopos autorizados para o usuário. Quando ela for autenticada por meio de um token de autorização, os escopos associados ao usuário serão restringidos pelos escopos informados no momento da criação do token, permitindo assim a autorização do uso do sistema com um conjunto mais restrito de privilégios.

Escopos que restringem privilégios

Escopos de autorização normalmente são utilizados para delimitar uma operação ou sub-recurso de uma API, permitindo que o administrador controle o acesso do usuário a eles. Via de regra, associar um escopo a um usuário ou a um token de autorização concede permissão a algo. No entanto, também é uma prática bem aceita o uso de escopos com o objetivo de restringir o privilégio de um usuário a um determinado recurso. Por exemplo:

  • api.vfs: concede acesso completo a Virtual File System.
  • api.vfs.readOnly: concede acesso de somente leitura a Virtual File System.

Devemos observar que neste caso, ao associar um usuário ao escopo api.vfs.readOnly, estaremos retirando o poder de escrita do usuário nessa API de forma definitiva. Mesmo que o usuário crie um token de autorização sem a indicação explícita desse escopo, a configuração do usuário prevalecerá sobre a do token. Tokens de autorização sempre restringem privilégios que o usuário já possui, eles jamais podem ser utilizados para ampliar ou elevar privilégios.

Escopos de autorização de segurança e do Engine

A maioria dos escopos de autorização são utilizados para controlar o acesso do usuário às APIs HTTP do sistema, no entanto alguns escopos são utilizados para controlar privilégios especiais no uso das APIs nativas do Engine. São eles:

  • security.changeUserPassword: permite um usuário modificar a senha de um outro usuário, privilégio equivalente ao dos participantes do grupo Administradores.
  • security.externalAccess: indica que o usuário pode logar remotamente a partir de uma outra base de dados, privilégio equivalente ao da permissão “Acesso remoto a partir de outra base” existente nas políticas de segurança.
  • engine.shutdown: permite a utilização das APIs engine.exit() e engine.restart() para finalizar e reiniciar um Engine programaticamente, inclusive de forma remota, privilégio equivalente ao da permissão “Reinício do Engine remoto” existente nas políticas de segurança.

Processo Escopos de autorização

Caminho: Admin > Segurança > Escopos de autorização.

Neste processo é possível visualizar e criar escopos de autorização. Via de regra, apenas o fornecedor do sistema e desenvolvedores responsáveis por customizações mais complexas precisam criar novos escopos.

Nome: nome do escopo. Deve-se adotar um nome curto, sem espaços, que indique a API e operação autorizada. Diferentemente de outros sistemas, não é comum um escopo de autorização indicar um recurso, pois os recursos normalmente são representados por classes de dados do sistema e o controle de acesso às classes é configurado via Permissões.

Descrição: de uma forma sucinta, indica o propósito do escopo. Essa informação é exibida nas interfaces que configuram os escopos associados aos usuários e na criação de tokens de autorização.

APIs HTTP

Grade que exibe as rotas das APIs HTTP que serão autorizadas ou desautorizadas ao atribuir o escopo a um usuário ou token de autorização.

Processos auxiliares

Rotas

Caminho: Desenvolvimento > APIs HTTP > Rotas.

Processo que exibe informações técnicas de todas as rotas das APIs HTTP publicadas pelo sistema, indicando se elas requerem a autenticação de um usuário e os escopos necessários para a sua utilização.