7361972 DSAUBE-10407 DT Token Cartão Virtual

01. DADOS GERAIS

Produto:	TOTVS Saúde Planos
Linha de Produto:	-
Segmento:	Saude
Módulo:	PLANO DE SAUDE SIGAPLS
Função:	Não se aplica
Ticket:	7361972
Requisito/Story/Issue (informe o requisito relacionado) :	DSAUBE-10407

02. SITUAÇÃO/REQUISITO

Implementada melhoria que permite o processo de validação do Token de Cartão virtual gerado por aplicativo.

O Token é uma senha numérica de 6 a 8 dígitos gerada por Aplicativo, que é informada pelo beneficiário no momento do atendimento e validada pelo sistema de Gestão ( PLS ), servindo como um segundo fator de autenticação, assegurando que quem está sendo atendido é mesmo o beneficiário portador da carteirinha informada.

03. SOLUÇÃO

Para que a validação seja possível, tanto o Aplicativo quanto o PLS devem ser capazes de gerar um mesmo Token para um mesmo usuário em um mesmo intervalo de tempo. Para isso, é necessário o compartilhamento, entre Aplicativo e PLS, de uma Chave (Seed) e alguns "parâmetros de alinhamento" para geração desse Token. Nesta implementação, esse compartilhamento é feito no momento do login.

04. DEMAIS INFORMAÇÕES

Criação de campo e do valid de alguns existentes.

Código do Pacote: 008174.

Criação na tabela SX3:

X3_CAMPO	X3_TAMANHO	X3_PICTURE	X3_TITULO	X3_CONTEXT	X3_VISUAL
BA1_TKSEED	128	@!	Token Seed	1 - Real	1 - Alterar

Alteração da tabela BE1 E BE4:

X3_CAMPO	X3_VALID
BE1_TOKEDI	If(Inclui, If(Empty(M->BE1_USUARI),.T.,PLSA090DAT("2")),.T.)

X3_CAMPO	X3_VALID
BE4_TOKEDI	If(Inclui, If(Empty(M->BE4_USUARI),.T.,PLBE4USUAR()),.T.)

Foram criados alguns parâmetros na X6.

X6_VAR	X6_TIPO	X6_DESCRIC	X6_DESCRIC 1	X6_CONTEUD
MV_PLSTKST	N	Tipo de Seed Gerado	1=Text;2=Base64;3=Hex	1
MV_PLSTKSH	N	Define o tamanho do Seed gerado.	3=SHA1;5=SHA256;7=SHA512	5
MV_PLSTKDG	N	Número Dígitos Token	6, 7 ou 8	6
MV_PLSTKTS	N	Token Time Step	Valor de tempo em segundos	1800

O processo completo de Geração e Validação do Token , pode ser visualizado a seguir.

Dessa forma, esta implementação abrange as seguintes funções e processos:

1 - Função PLSTKSEEDG que gera Chave (seed) compartilhada entre PLS e Aplicativo para que ambos gerem o mesmo Token para um mesmo intervalo de tempo. O seed gerado é gravado no registro do usuário (BA1_TKSEED):

Sintaxe

PLSTKSEEDG(cMatric, lAtualiza)

Parâmetros

Nome	Tipo	Descrição	Obrigatório
cMatric	caractere	Matrícula do Beneficiário	x
lAtualiza	booleano	Atualiza BA1_TKSEED	x

Retorno

aRet[1] boolean Status de Retorno

aRet[2] caractere Seed Gerado

Parâmetros de Sistema envolvidos

X6_VAR	X6_TIPO	X6_DESCRIC	X6_DESCRIC 1	X6_CONTEUD
MV_PLSTKST	N	Tipo de Seed Gerado	1=Text;2=Base64;3=Hex	1
MV_PLSTKSH	N	Define o tamanho do Seed gerado.	3=SHA1;5=SHA256;7=SHA512	5

Pontos de Entrada

PTKSEEDG

Descrição: Retorna Seed customizado para ser utilizado na Geração do Token. O mesmo é gravado no registro do usuário (BA1_TKSEED):

Parâmetros:

Nome	Tipo	Descrição	Obrigatório
cMatric	caractere	Matrícula do Beneficiário	x

2 - Inclusão, no método de criação e login de usuário da api de integração PLS x Aplicativo, de parâmetros de alinhamento para gereção do Token. São eles: Seed, Tipo do Seed, Tipo do Algoritmo a ser utilizado na geração do Token, Número de Digitos do Token e Intervalo de validade do Token em segundos (30min = 1800seg, conforme Manual):

Foram incluidos os seguintes Objetos Custom, dentro dos Objetos Beneficiários retornados pelo método de login da api mobile padrão:

Seed para Geração do Token:

Chave: "Seed"
Valor: Seed do Beneficiário, gerado pela função PLSTKSEEDG.

Algoritmo a ser utilizado na geração do Token:

Chave: "hash"

Valor: "SHA-1", "SHA-256" ou "SHA-512", dependendo do parâmetro MV_PLSTKSH

Tipo do Seed para Geração do Token:

Chave: "seedType"

Valor: "Text", "Base64" ou "Hex", dependendo do parâmetro MV_PLSTKST

Número de Dígitos dos Tokens a serem gerados:

Chave: "digits"

Valor: 6, 7 ou 8, dependendo do parâmetro MV_PLSTKDG

Intervalo de validade do Token

Chave: "timeStep"

Valor: Período de Tempo, em segundos, dentro do qual um Token é válido. Depende do parâmetro MV_PLSTKTS.

Exemplo de Objeto Custom gerado para um Beneficiário:

...

"beneficiarios": [

{

"nome": "EDSON ARANTES DO NASCIMENTO",

"nomeTitular": "EDSON ARANTES DO NASCIMENTO",

"matricula": "00010001000002006",

...

"custom": [

{

"valor": "uAbs7YWLcIigsXdqiCzM",

"chave": "seed"

},

{

"valor": "SHA-1",

"chave": "hash"

},

{

"valor": "Text",

"chave": "seedType"

},

{

"valor": 6,

"chave": "digits"

},

{

"valor": 1800,

"chave": "timeStep"

}

],

...

],

...

Parâmetros de Sistema envolvidos

X6_VAR	X6_TIPO	X6_DESCRIC	X6_DESCRIC 1	X6_CONTEUD
MV_PLSTKST	N	Tipo de Seed Gerado	1=Text;2=Base64;3=Hex	1
MV_PLSTKSH	N	Define o tamanho do Seed gerado.	3=SHA1;5=SHA256;7=SHA512	5
MV_PLSTKDG	N	Número Dígitos Token	6, 7 ou 8	6
MV_PLSTKTS	N	Token Time Step	Valor de tempo em segundos	1800

Importante!!!

APIs customizadas para integração com APP

Caso a operadora não utilize a API de integração mobile padrão, ela deverá incluir, na API customizada, todas as informações necessárias para alinhamento sobre a geração do Token. Dentre essas informações, é obrigatória a geração do Seed do Token utilizando-se a função PLSTKSEEDG descrita acima. Somente dessa forma será possível utilizar o processo padrão de validação do Token nos processos de Autorização.

3 - Funções de Geração e Validação do Token utilizando algoritmo TOTP (RFC6238 - https://tools.ietf.org/html/rfc6238 ). Essas funções são responsáveis por gerar, no PLS, o mesmo Token do Aplicativo para um determinado intervalo de tempo, de acordo com os parâmetros de alinhamento, e compará-lo com o Token informado no atendimento:

Função

PLSTOTPGEN

Descrição

Gera um Token genérico, baseado no algoritmo TOTP, de acordo com os parâmetros da função.

Sintaxe

PLSTOTPGEN(cK, nX, hashType, nKType, nXType, nDigits, cTTest)

Parâmetros

Nome	Tipo	Descrição	Obrigatório
cK	caractere	Seed	x
nX	integer	Time Step	x
hashType	integer	Função hash utilizada: (3=SHA-1; 5=SHA-256; 7=SHA-512)	x
nKType	integer	Tipo do Seed: (1=Text; 2=Base64; 3=Hex)	x
nXType	integer	Tipo do Input: (1=Text; 2=Base64; 3=Hex)	x
nDigits	integer	Número de Dígitos	x
cTTest	caractere	Input específico que pode ser utilizado para gerar o TOTP para um intervalo de tempo (timestamp) específico	x

Retorno

cRet caractere Token gerado

-----

Função

PLSTOKGENE

Descrição

Gera um Token específico, baseado no algoritmo TOTP, para um beneficiário específico de acordo com a hora atual do servidor.

Sintaxe

PLSTOKGENE(cMatric)

Parâmetros

Nome	Tipo	Descrição	Obrigatório
cMatric	caractere	Matrícula do Beneficiário	x

Retorno

aRet[1] boolean Status de Retorno da Função

aRet[2] caractere Token Gerado

-----

Função

PLSUTOKVLD

Descrição

Valida se um Token está correto para um Beneficiário específico em um intervalo de tempo específico.

Sintaxe

PLSUTOKVLD(cMatric, cToken)

Parâmetros

Nome	Tipo	Descrição	Obrigatório
cMatric	caractere	Matrícula do Beneficiário	x
cToken	caractere	Token a ser validado	x

Retorno

aRet[1] boolean Se Token é valido ou não

aRet[2] caractere Token Correto

Importante!!

Existem alguns sites na internet que geram Tokens utilizando o algoritmo TOTP. Eles foram utilizados para validar a implentação da função de geração do Token (PLSTOTPGEN) implementada. Caso haja interesse de conferência, é importante ressaltar que esses sites, normalmente, utilizam o Seed em formato Base32. Então, para isso, como o Seed implementado no PLS pode possuir apenas os formatos Texto, Base64 e Hexadecimal, é necessária a transformação em Base32 antes de inputá-lo no algoritmo no site de conferência.

Exemplo para testes.:

Seed Gerado para o Beneficiário 00010001000002006 = xOS8KQ9WPsTU23PjPbJD em formato texto, no momento do login;
Utilizar site https://emn178.github.io/online-tools/base32_encode.html para transformar text em Base32. Resultado: PBHVGOCLKE4VOUDTKRKTEM2QNJIGESSE

3. Utilizar Base32 como input do site https://totp.danhersam.com/ para geração do Token TOTP. Resultado: 298014

4. Verificar durante atendimento que Token gerado no sistema é o mesmo que o gerado pelo site de verificação:

4 - Inclusão de novo Motivo de Críticas do Sistema específico para a validação do Token;

Para funcionamento correto da melhoria, a seguinte Crítica de Sistema deve ser cadastrada:

Proprietário:	Código Glosa:	Descrição:	Tipo:	Ativa?:	Justif.Obr.:	Analisar:	Glosa TISS:	Desc. Glosa:
BCT_PROPRI = 5	BCT_CODGLO = 87	BCT_DESCRI = Token Inválido	BCT_TIPO = 1	BCT_ATIVA = 1	BCT_RESOBR = 0	BCT_LOCANA = 1	BCT_GLTISS = 1011	BCT_DESTIS = IDENTIFICACAO DO BENEFICIARIO NAO CONSISTENTE

Obs.: Nova glosa disponível no arquivo bct-motivo_de_criticas.csv, para carregamento automático.

5 - Processo de validação do Token dentro do Atendimento de Autorização SADT;

Iniciar um Atendimento do Tipo Autorização SADT e preencher a Matrícula do Beneficiário.

Informar Token.

Caso não seja válido, o sistema exibirá críticas.

Caso o parâmetro MV_PLSCABC esteja ativado, o sistema permitirá a continuação do Atendiemento com status não autorizado e gravará as críticas. Caso contrário, o atendimento não poderá ser concluído.

6 - Processo de validação do Token dentro do Atendimento de Solicitação de Internação;

Iniciar um Atendimento do Tipo Solicitação de Internação e preencher a Matrícula do Beneficiário.

Informar Token.

Caso não seja válido, o sistema exibirá críticas.

Caso o parâmetro MV_PLSCABC esteja ativado, o sistema permitirá a continuação do Atendiemento com status não autorizado e gravará as críticas. Caso contrário, o atendimento não poderá ser concluído.

7 - Processo de validação do Token no PTU Online

Iniciar um Pedido de Autorização, via PTU Online, incluindo o Token de Usuário, conforme exemplo a seguir.

<v80:pedidoAutorizacaoWS>

...

<v80:pedidoAutorizacao>

<v80:identificacaoBeneficiario>

...

<v80:codigoIdentificacao>0001000002057</v80:codigoIdentificacao>

...

</v80:identificacaoBeneficiario>

...

<v80:token>301039</v80:token>

<v80:blocoServicoPedido>

<v80:pedidoServico>

<v80:servico>

<v80:sqitem>1</v80:sqitem>

<v80:tipoTabela>22</v80:tipoTabela>

<v80:codigoServico>10101012</v80:codigoServico>

</v80:servico>

<v80:quantidadeServico>1</v80:quantidadeServico>

<v80:tpAnexo>9</v80:tpAnexo>

</v80:pedidoServico>

<v80:pedidoServico>

<v80:servico>

<v80:sqitem>1</v80:sqitem>

<v80:tipoTabela>22</v80:tipoTabela>

<v80:codigoServico>40301060</v80:codigoServico>

</v80:servico>

<v80:quantidadeServico>1</v80:quantidadeServico>

<v80:tpAnexo>9</v80:tpAnexo>

</v80:pedidoServico>

</v80:blocoServicoPedido>

...

</v80:pedidoAutorizacao>

</v80:pedidoAutorizacaoWS>

Caso o Token informado não seja válido, o sistema responde a solicitação com a crítica correspondente, e grava o atendimento com os procedimentos negados e respectivas críticas.

Resposta:

...

...

<descricaoServico>CONSULTA EM CONS...</descricaoServico>

</servico>

<descricaoMensagemEspec>Token Invalido.</descricaoMensagemEspec>

</mensagensEspecificas>

</respostaPedidoServico>

<descricaoServico>ACIDO ASCORBICO VITAMINA C - PESQ...</descricaoServico>

</servico>

<descricaoMensagemEspec>Token Invalido.</descricaoMensagemEspec>

</mensagensEspecificas>

</respostaPedidoServico>

</blocoServicoRespostaPedido>

No sistema:

8 - Processo de validação do Token no TissOnline

Iniciar uma Solicitação SADT, via Tiss Online, incluindo o Token de Usuário no campo "codAutorizacao", conforme exemplo a seguir.

<ans:solicitacaoProcedimentoWS ... >

<ans:cabecalho>

<ans:identificacaoTransacao>

<ans:tipoTransacao>SOLICITACAO_PROCEDIMENTOS</ans:tipoTransacao

...

</ans:identificacaoTransacao>

<ans:Padrao>3.05.00</ans:Padrao>

...

</ans:cabecalho>

<ans:solicitacaoProcedimento>

<ans:solicitacaoSP-SADT>

...

<ans:codValidacao>123456</ans:codValidacao>

...

<ans:dadosBeneficiario>

<ans:numeroCarteira>00010001000002057</ans:numeroCarteira>

...

</ans:dadosBeneficiario>

<ans:procedimentosSolicitados>

<ans:procedimento>

<ans:codigoTabela>22</ans:codigoTabela>

<ans:codigoProcedimento>40301060</ans:codigoProcedimento>

<ans:descricaoProcedimento>ACIDO...</ans:descricaoProcedimento>

</ans:procedimento>

<ans:quantidadeSolicitada>1</ans:quantidadeSolicitada>

</ans:procedimentosSolicitados>

</ans:solicitacaoSP-SADT>

</ans:solicitacaoProcedimento>

...

</ans:solicitacaoProcedimentoWS>

Caso o Token informado não seja válido, o sistema responde a solicitação com a crítica correspondente, e grava o atendimento com os procedimentos negados e respectivas críticas.

Resposta:

<ans:autorizacaoProcedimentoWS xmlns:ans="http://www.ans.gov.br/padroes/tiss/schemas">

<ans:cabecalho>

<ans:identificacaoTransacao>

<ans:tipoTransacao>RESPOSTA_SOLICITACAO</ans:tipoTransacao>

...

</ans:identificacaoTransacao>

...

<ans:cabecalho>

<ans:autorizacaoProcedimento>

<ans:autorizacaoServico>

<ans:dadosAutorizacao>

...

<ans:numeroGuiaOperadora>000120201000000076</ans:num...>

</ans:dadosAutorizacao>

<ans:dadosBeneficiario>

<ans:numeroCarteira>00010001000002057</ans:numeroCarteira>

...

</ans:dadosBeneficiario>

<ans:servicosAutorizados>

<ans:servicoAutorizado>

<ans:sequencialItem>0001</ans:sequencialItem>

<ans:procedimento>

<ans:codigoTabela>22</ans:codigoTabela>

<ans:codigoProcedimento>40301060</ans:codigoProcedimento>

<ans:descricaoProcedimento>ACIDO AS...</ans:descricaoProced...>

</ans:procedimento>

<ans:quantidadeSolicitada>1</ans:quantidadeSolicitada>

<ans:quantidadeAutorizada>0</ans:quantidadeAutorizada>

<ans:motivosNegativa>

<ans:motivoNegativa>

<ans:codigoGlosa>1011</ans:codigoGlosa>

<ans:descricaoGlosa>IDENTIFICACAO DO BENEFICIARIO NAO CONSISTENTE</ans:descricaoGlosa>

</ans:motivoNegativa>

</ans:motivosNegativa>

</ans:servicoAutorizado>

No sistema:

X6_VAR	X6_TIPO	X6_DESCRIC	X6_DESCRIC 1	X6_CONTEUD
MV_PLSTKST	N	Tipo de Seed Gerado	1=Text;2=Base64;3=Hex	1
MV_PLSTKSH	N	Define o tamanho do Seed gerado.	3=SHA1;5=SHA256;7=SHA512	5
MV_PLSTKDG	N	Número Dígitos Token	6, 7 ou 8	6
MV_PLSTKTS	N	Token Time Step	Valor de tempo em segundos	1800

Importante!!

Para funcionamento correto, deve-se, também, atualizar o binário do appserver com a versão 7.00.191205P-20201210

05. ASSUNTOS RELACIONADOS

<Não se aplica>

Árvore de páginas

7361972 DSAUBE-10407 DT Token Cartão Virtual

01. DADOS GERAIS

02. SITUAÇÃO/REQUISITO

03. SOLUÇÃO

04. DEMAIS INFORMAÇÕES

05. ASSUNTOS RELACIONADOS