Plug-ins: insoft-api e insoft-base-api

richardaltmayer

Procurando abstrair funcionalidades básicas das APIs construídas pela Insoft4, foram construídos plug-ins que possuem tal objetivo.

Para o correto funcionamento das APIs que utilizarem estes plug-ins, é necessário que a sua implantação seja acompanhada da implantação da API de autenticação insoft-auth.

Os plug-ins estão configurados sob groupId padrão (br.com.insoft4) dos plug-ins da Insoft4. Desta forma, a sua injeção nos projetos das APIs dá-se da seguinte forma:

compile "br.com.insoft4:insoft-api:<version>"

compile "br.com.insoft4:insoft-base-api:<version>"

Variações

insoft-api: para APIs que utilizem Grails 2.5.6 e Java 8.
insoft-base-api: para APIs que utilizem Grails 2.3.11 e Java 7.

Com a atualização tecnológica das aplicações, a tendência é que o plugin insoft-base-api seja descontinuado.

Objetivos

Autenticação

O processo de autenticação, através da comunicação com a API de autenticação insoft-auth, está disponível nos plug-ins, não sendo necessária a implementação de código em cada API.

O controller br.com.insoft4.api.v1.AutenticacaoController é controlado por versão. Assim, o acesso aos endpoints deste controller deve considerar o seu namespace. Exemplo:

<url base da api>/v1/autenticacao/

Os endpoints previstos neste controller são:

index [POST] [/v1/autenticacao/]: realiza a autenticação do usuário, mediante parâmetros recebidos.
tenant [POST] [/v1/autenticacao/tenant/]: valida o tenant em cenários de aplicação que necessitem (exemplo: ambiente de vários clientes do Ponto Soft Ex).
logout [GET] [/v1/autenticacao/logout/]: invalida o token da sessão do usuário.

Segurança

A aplicação da camada de segurança também é disponibilizada pelos plug-ins, sendo realizada através da classe br.com.insoft4.api.ApiFilters , que realiza a validação da requisição, considerando:

Token existente na requisição
Token válido, mediante comunicação com a API de autenticação insoft-auth.
Valor definido na configuração api.security, quando existir.

Configurações

api.authenticator.url

Esta configuração é obrigatória.

URL de comunicação com o autenticador, utilizado pela API para efetuar a autenticação do usuário. Exemplo:

api.authenticator.url = "http://localhost:8081/insoft-auth"

api.key.enabled

Esta configuração é opcional.

Habilita uma camada de validação adicional, validando a presença de uma chave de API.

api.key.enabled = true // false

api.key.name

Esta configuração é opcional.

Define o nome da chave a ser validada durante as requisições à API.

api.key.name = "Api-Key"

api.key.value

Esta configuração é opcional.

Define o valor da chave a ser validada durante as requisições à API.

api.key.value = "xkkWKmmFeZzzUtTtY4lw7c1JZtLcQlNl"

api.security

Esta configuração é opcional.

Visando incluir uma maior granularidade na definição de segurança, uma possibilidade de configuração foi incluída para definir de regras de acesso aos endpoints da API para os usuários, de acordo com:

api.security = [[
    // Define as regras de acesso dos endpoints para o usuário
    username: "USUARIO", 
    allowed: [
        // Permite acesso à todos os endpoints do controller Empresa    
        [controller: "empresa"],
        // Permite acesso aos endpoints "save" e "update" do controller Setor
        [controller: "setor", action: ["save", "update"]],
        // Permite acesso aos endpoints cujo método de requisição do controller Evento seja POST ou GET
        [controller: "evento", method: ["POST", "GET"]],
        // Permite acesso aos endpoints de todos os controllers, onde o método da requisição seja GET
        [controller: "*", method: ["GET"]] 
    ],
    denied: [
        // Bloqueia acesso à todos os endpoints do controller Filial
        [controller: "filial"] 
    ]
], [
    username: "USER",
    allowed: [/* ... */],
    denied: [/* ... */]
]]