Protheus :: Autenticação WebService versão 3.0 (Documentação)

Uma breve documentação do WS publicado no "post": Protheus :: Autenticação WebService versão 3.0 :

WS u_wsUserValid.
É responsável por autenticar usuário e senha e retornar um “token” para consumo dos métodos dos demais WebService

Métodos:

“ValidUserWs” e “IsAuthenticated”

O método “ValidUserWs” receberá como argumentos de entrada:

“UserWs”, “UserWsPasswd”, “CheckSum”, “HASHMD5UserAndPsw”, “Language” e “Embaralha”

E retornara: Token

Descrevendo cada uma das entradas:

UserWs -> Identifica o usuário a ser validado/autenticado. Essa informação deverá ser enviada em Encode64 para que o método o decodifique
Poderá ser passado o Encode64 tanto do valor original do usuário quando o seu MD5 Hash. Vai depender do parâmetro HASHMD5UserAndPsw.

Quando o parâmetro HASHMD5UserAndPsw estiver com o valor “true”, o UserWs deverá receber o Encode64 do Hash do usuário.

Quando o parâmetro HASHMD5UserAndPsw estiver “setado” como ” false”, o UserWs deverá receber o Encode64 do usuário.

UserWsPasswd -> Senha do usuário a ser validado/autenticado. Essa informação deverá ser enviada em Encode64 para que o método a decodifique. Poderá ser passado o Encode64 tanto do valor original da senha quando o seu MD5 Hash. Vai depender do parâmetro HASHMD5UserAndPsw.

Quando o parâmetro HASHMD5UserAndPsw estiver com o valor “true”, o “UserWsPasswd “ deverá receber o Encode64 do Hash da senha do usuário.

Quando o parâmetro HASHMD5UserAndPsw estiver “setado” como “false”, o UserWsPasswd deverá receber o Encode64 da senha do usuário.

CheckSum -> Receberá um valor numérico que relacionará o usuário a uma senha.

Poderão existir tantos usuários e senhas quanto necessários.

E essa informação deverá existir nas duas pontas. Tanto no fornecedor do serviço quando no client consumidor do serviço.

Os usuários e senhas, no protheus, ficarão em um arquivo .ini de nome u_wsuservalid.ini, devendo ficar nas pasta \wstoken\, abaixo do rootpath do protheus.

Estrutura do arquivo:

[UserName]
naldodj
Carla
Naldo&Carla

[UserPassWord]
b3d28e7f822dac10b74101712651597ba152c2fc
Ly9QYXJhIG8gRGVjb2RlNjQgdXNlOiBodHRwOi8vd3d3Lm9waW5pb25hdGVkZ2Vlay5jb20vZG90bmV0L3Rvb2xzL2Jhc2U2NGRlY29kZS8qLw==
9dd867e76e02c3fa10ae50dcc11081c5d2adec57
6148ea40e060b81e0baa6927adffa3b847e8bf38
9dd867e76e02c3fa10ae50dcc11081c5d2adec57

Observe que o numero de senhas é maior que o numero de usuários. Isso quer dizer que eles não estão diretamente relacionados, posso ter 1 usuário para “n” senhas, quanto “n” usuários para 1 senha, ou ainda, “n” usuários para “n” senhas.
O que vai definir qual senha esta vinculada a um determinado usuário é o Checksum: uma soma numérica posicional entre usuários e senhas.
Exemplo:

Vamos supor que informamos o usuário: naldodj e a senha: b3d28e7f822dac10b74101712651597ba152c2fc

No exemplo ambos possuem posição: 1,1
Então o checksum será 1+1=2

Se informássemos a senha: 6148ea40e060b81e0baa6927adffa3b847e8bf38 o “CheckSum” seria 1+4=5

Ou seja, no primeiro exemplo o checksum seria 2 e no segundo 5.

Lembrando que antes de enviar o usuário e a senha essas deverão ser codificadas via Encode64, verificar o parâmetro HASHMD5UserAndPsw para verificar se, antes do Encode64 será calculado o “Hash”.

As mesmas informações de senha contidas nesse arquivo .ini deverão constar em algum lugar no “client” consumidor do WS com a mesma ordem e mesmo conteúdo, sob pena do checksum invalidá-los no protheus, quando o diretório \wstoken\ não existir será criado automaticamente quando qualquer método do WS U_WsUserValid for executado o mesmo para o arquivo de configuração: u_wsuservalid.ini que já terá valores DEFAULT para usuários e senhas. Esses valores deverão ser modificados de acordo com a necessidade do client consumidor do WS e fornecedor do serviço.

LEMBRANDO QUE EM AMBAS AS PONTAS, DEVERAO TER O MESMO CONTEUDO E NA MESMA ORDEM E QUE O NOME DOS USUÁRIOS E SENHA SÃO “Case sensitivity”

O arquivo de configuração u_wsuservalid.ini, além das configurações de usuário e senha, também definirá o Timeout para as mensagens, então, a configuração do u_wsuservalid.ini deverá ser:

[UserName] que conterá a lista de usuários para consumo dos métodos do WS
[UserPassWord] que conterá a lista de senhas que poderão ser vinculadas aos usuários
[TimeOut] que conterá, em segundos, a informação de TimeOut para validade de uma mensagem recebida pelo método ValidUserWs do WS u_wsUserValid

HASHMD5UserAndPsw -> Receberá o valor true se, para o usuário e senha, forem enviados apenas o MD5 Hash e false se forem enviados os usuários e senhas originais, lembrando que antes de enviar o usuário e senha esses deverão ser codificados usando o Encode64.

Language -> Considerando que as mensagens (TOKENS) enviadas para autenticação de usuários são baseadas nas descrições constantes na TABELA genérica do Protheus, a SX5 e que essa possui a descrição em Português (PT), Inglês (ENG) e espanhol (SPA) esse parâmetro, que é opcional, deverá receber os seguintes conteúdos:

PT ou ENG ou SPA ou (brancos).

É útil para ter uma gama maior de mensagens uma vez que o conteúdo possível de mensagens serão o total de registros da tabela genérica do siga multiplicado por 3 quando o parâmetro for brancos, a mensagem será baseada em informações do sistema, como data, hora, segundos + algumas constantes.

Embaralha -> É um parâmetro do tipo Boolean, e irá definir se a mensagem deverá ser "embaralhada" antes de ser enviada, true, embaralha, false não.

Token -> Retorno do método. É uma string contendo a mensagem a ser decodificada no client do WS. Ela será enviada com a codificação em Encode64, o consumidor do WS deverá decodificá-la usando o Decode64, calcular o seu Hash e, para consumir qualquer método dos demais WS deverá passar esse Hash (também codificado em Base64).

Método IsAuthenticated do WS u_wsUserValid:

O método IsAuthenticated do Ws u_wsUserValid receberá como argumento de entrada:

Token -> Esse token deverá estar codificado em Base64 e deverá corresponder ao Token gerado pelo método ValidUserWs do WS u_wsUserValid, ele é o responsável por autenticar o consumidor dos demais WS.

Irá retornar:

lAuthenticated -> com o valor true se usuário foi devidamente autenticado e false caso contrário, e, dependendo do retorno o usuário poderá ou não consumir os métodos do serviço.

O método IsAuthenticated do WS u_wsUserValid, sempre que for autenticar uma mensagem, irá verificar se ela já "expirou" por Timeout, e se sim, irá invalidar o usuário.

WS u_wsClearMessages

O WS u_wsClearMessages serve como um "Garbage Collector", ele é o responsável por efetuar a limpeza das pilhas de mensagens geradas pelo método ValidUserWs do WS u_wsUserValid, receberá como argumentos de entrada: Token, ClearAllMD5Hash, MD5HashClear.

Token -> Receberá uma string em Base64 com o Hash da mensagem obtida através do método ValidUserWs do WS u_wsUserValid, ele é o responsável pela autenticação do usuário.

ClearAllMD5Hash -> do Tipo Boolean, indica ao método se deverá limpar todas as mensagens geradas ( valor true ) ou não ( valor false)

MD5HashClear -> Deverá receber uma string em Base64 com o Hash MD5 da mensagem a ser "limpa" (eliminada) da pilha de mensagens, se esse parâmetro for passado e o parâmetro ClearAllMD5Hash estiver com o valor "true" esse último será considerado como "false"

Esse método será útil para limpar as pilhas de mensagens em caso de queda dos serviços.

[]s

иαldσ dj

...

Ps.: Carlinha, só você mesmo para me fazer documentar e publicar isso...

...