/
Token TOTP - Cartão Virtual

Token TOTP - Cartão Virtual

1. Visão Geral

A funcionalidade de Token TOTP (Time-Based One-Time Password) aplicada ao Cartão Virtual tem como objetivo mitigar o uso indevido de credenciais compartilhadas, especialmente em cenários onde há:

  • Empréstimo de carteirinha (física ou digital)

  • Uso de prints do cartão virtual

  • Falta de validação de identidade presencial

O TOTP adiciona uma camada de autenticação dinâmica, exigindo que o usuário gere um código temporário no momento do atendimento.

2. Problema de Negócio

2.1 Cenário anterior

Antes da implementação:

  • Usuários compartilhavam carteirinhas

  • Clínicas nem sempre validavam documento de identidade

  • Prints do cartão virtual eram facilmente reutilizados

⚠️ Risco crítico: acesso indevido a serviços de saúde em nome de terceiros.

2.2 Limitação do cartão virtual

Apesar de eliminar o cartão físico:

  • O cartão virtual pode ser capturado via print

  • O print pode ser compartilhado instantaneamente

⚠️ Problema persistente: o cartão virtual isoladamente não garante identidade do portador.

3. Objetivo da Solução

Implementar um mecanismo que:

  • Comprove que o usuário está autenticado no momento do uso

  • Reduza a viabilidade de compartilhamento de acesso

  • Não dependa exclusivamente de validação manual (documento físico)

  • Diminua a iniciativa de fraude (token traz uma sensação de vigilância, que pode inibir a fraude sob a perspectiva de quem está emprestando o cartão).

4. Fluxo de Uso (Jornada)

4.1 Processo no atendimento

  1. Usuário abre o app e acessa o cartão virtual

  2. O token TOTP é exibido (ou gerado sob demanda)

  3. Profissional solicita o token

  4. Usuário informa o código exibido

  5. Operador digita o token no sistema do parceiro

  6. Sistema parceiro valida o token

Fluxo Simplificado

[Início] | [Atendimento presencial inicial ou digital] | |-- Recepciona beneficáirio |-- Inicia atendimento e informa dados do cartão (matrícula e outros dados) |-- Solicita o token TOTP para usuário que está sendo atendido | [Beneficiário] | |-- Acessa a rotina de cartão virtual |-- App calcula Token TOTP (offline) usando credenciais do cartão virtual |-- Repassa o token gerado para o atendimento | [Atendimento presencial inicial ou digital] | |-- Insere o token fornecido |-- Sistema de autorização calcula o Token TOTP para o usuário |-- compara se o token calculado é o mesmo que o token informado | [Resultado] |-- se tokens iguais = válido. Permite continuar a autorização. |-- se tokens diferentes = inválido. Impede a autorização. | [Fim]

4.2 Validação no sistema autorizador

  1. Recebe token digitado

  2. Recalcula o token com base nos mesmos parâmetros (configuração deve ser idêntica, tanto no Mosia Omnichannel quanto no sistema de autorização da sua operadora)

  3. Compara:

if (token_informado == token_calculado) autenticação válida else erro de autenticação

⚠️ Regra crítica: divergência resulta em negação de atendimento/autorização.

5. Arquitetura de Funcionamento

O modelo segue o padrão TOTP (RFC 6238), com as seguintes características:

  • Atualização periódica automática

  • Geração determinística baseada em parâmetros compartilhados

5.1 Princípio de funcionamento

O token é gerado de forma independente por:

  1. Aplicativo Mobile Saúde (cliente)

  2. Sistema do parceiro (ERP / autorizador)

Ambos utilizam:

  • Mesmo identificador (SEED)

  • Mesmos parâmetros (algoritmo, período, etc.)

  • Mesmo timestamp (sincronizado)

O token é gerado no próprio app da Mobile Saúde, a lógica é implementada de forma que não é consumida nenhuma API de terceiros e com isso a carteirinha podendo ser usada até mesmo em locais sem internet, todos os parametros devem ser configurados obrigatóriamente no Mosia Omnichannel para funcionar corretamente.

6. Parâmetros de Configuração

  1. Acesse o configurador público do Mosia Omnichannel (como acessar);

  2. Configurador de Funcionalidades > Serviços > Cartão Virtual;

  3. Na aba parametros configure os seguintes parametros que são obrigatórios;

6.1 Parâmetros obrigatórios

Parâmetro

Descrição

Valores aceitos

Parâmetro

Descrição

Valores aceitos

tokenAlgoritmo

Algoritmo de hash usado na geração do token

sha1, sha256, sha512

tokenDigitos

Quantidade de dígitos do código OTP

6 ou 8

tokenPeriodo

Intervalo de validade do token (segundos)

Ex: 30, 100, 1800

tipoEncodingSeed

Tipo de encoding do SEED

ascii, base64, hex, latin1, utf8

6.2 Configuração recomendada (padrão recomendado, e em uso em diversos clientes)

  • Algoritmo: SHA256

  • Dígitos: 6

  • Período: 1800 segundos

  • Encoding: HEX

7. SEED (Identificador do Beneficiário)

7.1 Definição

O SEED é o identificador único do beneficiário utilizado como base para geração do TOTP.

O SEED está presente no objeto de login do beneficiário, e não é um parâmetro a ser configurado.

7.2 Recomendação de uso

  • Utilizar preferencialmente um dado que seja único por usuário. Lembre-se que um mesmo usuário pode ter mais de um número de cartão, portanto recomendamos fortemente o uso do número do cartão (carteirinha).

7.3 Regras de consistência

  • O SEED deve ser idêntico em todos os sistemas integrados

  • Não pode haver diferenças de encoding entre Mobile Saúde e ERP

8. Conversão do SEED

Antes da utilização no TOTP, o SEED deve seguir o fluxo:

8.1 Pipeline de conversão

  1. String original (ex: matrícula)

  2. Conversão para HEX

  3. Conversão de HEX para BASE32

  4. Uso do BASE32 no gerador TOTP externo (validação)

8.2 Observação importante

  • O sistema interno pode operar com HEX

  • Ferramentas externas de validação frequentemente exigem BASE32

9. Validação Externa

Aplicabilidade: durante a implementação, é frequente que os tokens gerados entre sistemas (Mobile Saúde x Sistema Autorizador) sejam diferentes. O motivo geralmente é diferença no fluxo de cálculo desse token.

Para facilitar o entendimento de “qual token está correto”, sugerimos o uso de um algoritmo de internet, formatado para calcular de forma independente os tokens com base em parâmetros informados no próprio site, sem exigir integração ou preparação prévia.

Recomendamos a seguinte ferramenta online:

6.1 Capacidade da ferramenta

Permite simular:

  • Algoritmo (SHA1 / SHA256 / SHA512)

  • Período

  • Número de dígitos

  • Seed em BASE32 (LEMBRAR DE USAR A CONVERSÃO DO SEED EXPOSTA NO PASSO 8).

image-20260410-192533.png

 

10. Fluxo de Geração do Token

7.1 Processo padrão

  1. Obter matrícula do beneficiário

  2. Converter matrícula → HEX

  3. Converter HEX → BASE32

  4. Aplicar parâmetros:

    • SHA256

    • 6 dígitos

    • 1800 segundos

    • encoding HEX (interno)

  5. Gerar TOTP

  6. Validar consistência entre sistemas

11. Requisitos de Integração

8.1 Mobile Saúde ↔ ERP

Os sistemas devem manter:

  • Mesma configuração de algoritmo

  • Mesma configuração de período

  • Mesma quantidade de dígitos

  • Mesmo padrão de encoding

8.2 Regra crítica

Qualquer divergência entre Mobile Saúde e ERP resulta em falha de autenticação.

11. Configuração no Mobile Saúde

11.1 Acesso

  • Acessar painel de configuração de funcionalidades

  • Navegar até módulo: Cartão Virtual

11.2 Parâmetros TOTP

Configurar:

  • Algoritmo: SHA256

  • Dígitos: 6

  • Período: 1800

  • Encoding: HEX

  • Token habilitado: true

11.3 SEED

  • Utilizar matrícula do beneficiário

  • Garantir consistência entre sistemas

  • Garantir que o atributo seed tenha sido informado no payload do método de login do app (1.1 - Login )

11.4 Aplicação das mudanças

Após alteração:

  • Reiniciar serviços

  • Realizar logout/login no app sandbox

  • Validar geração do token novamente

12. Configuração no ERP

12.1 Parâmetros obrigatórios

  • Algoritmo: SHA256

  • Dígitos: 6

  • Período: 1800

  • Seed (usar o mesmo, e garantir que a conversão segue os passos descritos no tópico 8)

12. Troubleshooting

12.1 Token não valida

Verificar:

  • Algoritmo idêntico entre sistemas

  • Dígitos iguais (6 vs 8)

  • Período igual (ex: 1800)

  • Encoding correto do SEED

  • Reinicialização após mudanças

12.2 Token diferente entre sistemas

Causas comuns:

  • SEED convertido incorretamente

  • HEX vs BASE32 inconsistentes

  • Cache não atualizado

  • Time drift entre sistemas

13. Testes Recomendados

13.1 Funcionais

  • Geração com SHA1, SHA256, SHA512

  • Teste de 6 e 8 dígitos

  • Validação de períodos variados

13.2 Integração

  • Mobile Saúde vs ERP

  • Mobile Saúde vs validador externo

  • Login completo no sandbox

13.3 Edge cases

  • Mudança de token no limite de tempo

  • SEED inválido ou incompleto

  • Seeds longos e curtos

  • Diferença de timezone

14. Riscos Identificados

  • Divergência de parâmetros entre sistemas

  • Falta de ferramenta oficial de validação centralizada

  • Conversão manual de SEED (erro humano)

  • Ambiguidade entre HEX e BASE32

15. Decisões Recomendadas

  • Padronização adotada:

    • SHA256

    • 6 dígitos

    • 1800 segundos

  • SEED baseado em matrícula do beneficiário

  • Necessidade de sincronização estrita entre sistemas

  • Necessidade de reinicialização após alterações.

Mobile Saúde - Mosia Omnichannel