oAuth

O REST server possui recurso de ativar a autenticação para as requisições HTTP.

Schemas de Autenticações disponíveis:

Basic
oAuth2

Basic

Para a autenticação Basic, é possível também determinar qual função irá fazer a verificação do usuário e senha enviados pela requisição.

Sendo assim, ao informar o nome da função para o onAuth, o tlppCore irá executar a função do usuário na primeira ação assim que chegar a requisição.

Configuração

A ativação da autenticação do serviço REST deverá ser feito para cada servidor configurado, ou seja, é possível ter autenticações diferentes ou até desativadas por servidor.

Porém, não será possível ter autenticações distintas para as Locations e ThreadPool distintas do mesmo servidor, nesse caso, todos terão a mesma regra de autenticação.

Nota: os trechos que estão ocultos foram substituídos por ... para facilitar a leitura. A configuração completa você pode consultar aqui

[HTTPSERVER]
Enable=1
Servers=HTTP_SRV
...

[HTTP_SRV]
TlppData='{"Authorization":{"scheme":"basic","OnAuth":"onAuthorization"}}'
...

Como a autenticação é um recurso essencialmente da camada tlppCore, sua configuração é feita através da chave [TlppData] da sessão do servidor.

Essa chave pode receber duas formas de valores, 1 - string em formato JSON diretamente, ou, 2 - Nome de arquivo JSON (com path completo ou não), com o conteúdo da configuração.
A segunda forma é útil quando seja necessário um JSON muito extenso, já que as chaves de INIs no appserver possuem uma limitação na quantidade de caracteres para ser usado.

Para ativar a autenticação, no JSON é preciso informar o modo e a função que será responsável pelas autenticações, sendo assim, é preciso um JSON conforme o formato a seguir:

{
    "Authorization": {
        "scheme": "basic",
        "OnAuth": "onAuthorization"
    }
}

Note que as informações passadas ao REST, estão dentro de uma chave em nó no JSON com o nome [Authorization], o modo é informado pela chave [scheme] e a função pela chave [OnAuth].

Nota: Necessário informar um nome válido de função e que esteja compilada no RPO correspondente no Environment do serviço REST, caso contrário, o tlppCore irá gerar um erro logo na subida do servidor e irá interromper o start, não ficando disponível.

Abaixo, seguem detalhes de como utilizar cada modo de autenticação disponível no REST server.

BASIC: Como se utiliza?

Ao receber uma requisição HTTP no servidor REST que esteja ativado o modo BASIC, o tlppCore verifica se no Header possui a seguinte informação:

Authorization: Basic {credenciais em base 64 no formato usuário:senha}

Nesse momento, ainda não é validado o conteúdo de usuário e senha e nem se ele tem o acesso requisitado, é validado somente se existe essa informação no Header, podendo ter 2 ações, sendo:

[1]

Caso não possua a informação ou não esteja no formato correto, o server não atende a requisição e retorna de imediato com a mensagem:

{"code":401,"detailedMessage":"","message":"Unauthorized"}

E no Header do HTML a seguinte informação:

WWW-Authenticate: Basic realm="Access to REST", charset="ISO-8859-1"

Com esse retorno, o requisitante tem a condição de adequar a requisição e enviá-la com a informação necessária.

[2]

Caso possua a informação e ela esteja com o formato esperado, então o server irá "Decodar" a base64 onde tenha o usuário:senha para poder realizar o parse da informação.

Após isso, com os dados já separados, é executada a função definida na chave [onAuth], seguindo a seguinte assinatura de funcionalidade .

Parâmetros

A função customizada recebe 2 (dois) parâmetros, sendo:

1 - cUser

Usuário a ser validado

2 - cPass

Senha a ser validada.

Retorno

O retorno é do tipo lógico [boolean], sendo .T. (true) para autenticação com sucesso ou .F. (false) para falha na autenticação.

Como o tipo retorno deve ser booleano, o server tem uma proteção para quando a função retorne algo diferente do exigido e irá converter o retorno para booleano, porém para esses casos sempre irá considerar o valor como FALSE.

Sendo assim, o comportamento do REST fica:

Tipo Retorno	Valor	Valor Considerado
boolean	true	true
boolean	false	false
nil	---	false
string	---	false
numeric	---	false
date	---	false
array	---	false
object	---	false

Importante ressaltar que, existindo essa função e o valor considerado for FALSE, será considerado como falha de autenticação.

Exemplo

function onAuthorization( cUser, cPass )

    local lRet := .F.

    lRet := cUser == 'test_user' .and. cPass == 'test_pass'

return lRet

Caso o retorno seja .F., ou o server considere o retorno inválido, o server não atende a requisição e retorna de imediato com a mensagem:

{"code":403,"detailedMessage":"","message":"Forbidden"}