Autenticacao mobile em React Native: login, token, refresh e sessao sem caos

Quase todo app corporativo comeca com a mesma impressao: basta colocar uma tela de login, salvar um token e seguir. Depois chegam os detalhes reais. O app abre sem saber se a sessao ainda vale, o token expira no meio da operacao, o usuario fica preso em loop de login, a fila offline guarda acao de quem ja saiu, o backend muda regra de autenticacao e o suporte nao consegue dizer se o problema esta no app, na API ou na sessao restaurada errado.

Em React Native, autenticacao nao e so uma tela inicial. Ela define como o app entra, quais rotas aparecem, onde o token fica, como a sessao volta apos reabrir o aplicativo e como o sistema reage quando a credencial vence. Quando essa base nasce improvisada, cada nova funcionalidade herda inseguranca e retrabalho.

Este guia organiza um fluxo pratico para tratar login, access token, refresh token, armazenamento seguro e comportamento de sessao sem transformar autenticacao em fonte permanente de caos.

1. Autenticacao e um fluxo de estados, nao apenas um formulario

A documentacao do React Navigation deixa isso bem claro ao modelar o app com estados como `isLoading`, usuario autenticado e usuario nao autenticado. Em outras palavras, o app precisa saber se esta restaurando a sessao, se ainda nao encontrou token ou se ja pode abrir a area protegida.

Esse desenho evita um erro comum: renderizar a tela errada antes de terminar a leitura da sessao local. O fluxo mais saudavel costuma ter pelo menos tres estados:

• bootstrap: o app ainda esta tentando restaurar a sessao;
• nao autenticado: mostrar login, recuperar senha ou onboarding;
• autenticado: liberar as rotas protegidas.

Quando o estado de bootstrap nao existe, o usuario ve flash de tela publica, menu indevido ou redirecionamento confuso antes de o app decidir para onde ir.

2. Mostre uma tela de carregamento antes de abrir navegacao protegida

No guia de auth flow, o React Navigation recomenda renderizar a SplashScreen antes do navigator quando o app ainda esta verificando o token salvo. A ideia e simples e poderosa: nao monte rotas erradas enquanto a sessao ainda esta indefinida.

Na pratica, o fluxo costuma ser:

1. abrir o app;
2. ler o token salvo com armazenamento seguro;
3. validar se aquela sessao ainda faz sentido;
4. so depois decidir se entra no fluxo autenticado ou no fluxo de login.

Esse detalhe melhora experiencia e tambem reduz bugs de estado. O artigo React Native para app corporativo ja tocava nisso ao separar claramente area publica, sessao e navegacao.

3. Access token e refresh token nao fazem o mesmo trabalho

Muitas equipes guardam um unico token e torcem para que ele dure para sempre. Em app corporativo, isso costuma falhar cedo. O access token normalmente representa a credencial usada nas chamadas do dia a dia. O refresh token existe para renovar sessao com mais controle, sem pedir login a cada pouco tempo.

Perguntas que precisam de resposta:

• qual token vai em cada requisicao?
• qual e a vida util aceitavel do access token?
• quando o app tenta refresh automatico?
• quando o app precisa pedir login de novo?
• o backend invalida refresh token antigo no logout ou rotacao?

Se essas regras nao forem combinadas com a API, o app entra em sintomas conhecidos: 401 em cascata, retry infinito, usuario deslogado sem explicacao ou sessao que parece ativa, mas nao consegue operar.

4. Token sensivel pede armazenamento seguro

A documentacao do Expo SecureStore informa que a biblioteca fornece armazenamento criptografado local para pares chave e valor. Ela tambem explica que, no Android, os valores ficam em SharedPreferences criptografado com Android Keystore, e que no iOS os dados usam Keychain Services.

Isso torna o SecureStore uma escolha natural para dados pequenos e sensiveis de sessao, como token e identificadores de autenticacao. Ao mesmo tempo, a propria documentacao alerta que esse armazenamento nao deve ser tratado como unica fonte de verdade para dados criticos e que payloads grandes podem ser rejeitados.

Regra pratica:

• token e segredo pequeno em armazenamento seguro;
• cache de leitura e fila maior em camada apropriada, nao no mesmo lugar;
• nunca assumir que sessao local sozinha substitui validacao com backend.

Isso conversa diretamente com a separacao explicada em offline, fila e sincronizacao com API.

5. Restaurar sessao nao significa confiar cegamente nela

No exemplo do React Navigation, o app le o token salvo e depois pode valida-lo em producao. Esse comentario da propria documentacao vale ouro: restaurar token nao e o mesmo que garantir sessao valida.

Ao reabrir o app, vale considerar:

• o token ainda nao expirou?
• o usuario foi revogado no backend?
• o ambiente da API mudou?
• o refresh ainda funciona?
• o app precisa buscar perfil antes de liberar a area protegida?

Uma sequencia prudente costuma ser: ler sessao local, tentar validar ou renovar, carregar perfil minimo, so entao liberar o app autenticado. Isso reduz o caso em que a interface entra, mas a primeira acao real falha logo depois.

6. Refresh precisa ser controlado para nao virar tempestade

O erro mais caro nao e token expirar. E varios requests falharem ao mesmo tempo e cada um tentar refresh por conta propria. Quando isso acontece, o app pode disparar varias renovacoes, sobrescrever estado ou cair em corrida entre chamadas.

Um desenho mais seguro costuma incluir:

• fila unica para refresh em andamento;
• requests aguardando a mesma renovacao quando fizer sentido;
• falha de refresh levando a logout controlado, nao a retry infinito;
• limpeza clara de credenciais quando a renovacao for recusada.

Do lado da API, tambem ajuda definir status previsiveis, corpo de erro coerente e logs claros. Por isso o material Checklist para API REST em producao continua importante para o mobile.

7. Logout precisa limpar mais do que a tela

Fazer logout nao e apenas navegar para a rota de login. O app precisa limpar o que ainda representa sessao daquele usuario.

Checklist minimo de logout:

• remover access token;
• remover refresh token quando existir localmente;
• limpar cabecalhos ou estado global em memoria;
• esvaziar dados sensiveis ligados ao usuario atual;
• revisar fila offline ou rascunhos que nao deveriam sobreviver para outro usuario;
• invalidar sessao no backend quando o fluxo pedir isso.

Sem essa limpeza, o proximo login pode herdar contexto indevido, cache antigo ou tentativa de sincronizacao criada por outra pessoa.

8. Biometria e bloqueio local pedem cuidado extra

O Expo SecureStore documenta que a opcao `requireAuthentication` pode invalidar a chave quando houver mudanca na biometria do aparelho, como adicionar uma nova digital. Tambem informa restricoes de Face ID em Expo Go e configuracao necessaria no app config.

Isso significa que biometria pode ser otima como camada adicional para reabrir area sensivel, mas nao deve ser assumida sem fallback.

Perguntas uteis:

• o app precisa biometria para tudo ou apenas para telas criticas?
• o que acontece se a chave for invalidada?
• o usuario consegue voltar pelo login normal?
• o time sabe explicar a permissao biometrica no contexto certo?

Biometria melhora protecao local, mas aumenta casos de borda. Vale entrar quando existe motivacao real, nao por moda.

9. Sessao em segundo plano tambem faz parte da experiencia

A documentacao do React Native AppState explica que a API informa se o app esta em foreground ou background e costuma ser usada para decidir comportamento com notificacoes. Essa mesma leitura ajuda autenticacao.

Exemplos de uso saudavel:

• revalidar sessao quando o app volta ao foreground depois de longo periodo;
• ocultar tela sensivel ao retornar do background quando a politica pedir;
• evitar continuar fluxo critico com token vencido apos horas parado;
• separar timeout real de sessao de simples troca rapida de app.

Nem todo retorno do background exige novo login. Mas tambem nao vale fingir que a sessao continua intacta depois de um dia inteiro sem revalidacao.

10. Offline e autenticacao precisam conversar

Um app corporativo pode ter fila local, cache e rascunho, mas isso nao significa que qualquer sessao vencida deva continuar operando como se nada tivesse acontecido. Offline e autenticacao precisam de contrato claro.

Decisoes comuns:

• permitir leitura offline limitada com sessao expirada, mas bloquear envio;
• manter rascunho local sem perder o trabalho do usuario;
• pedir reautenticacao antes de sincronizar fila pendente;
• marcar visualmente quando a operacao ficou pausada por sessao invalida.

Sem esse acordo, o app parece funcionar enquanto acumula acoes que nunca poderao subir com seguranca.

11. A API precisa diferenciar autenticacao, autorizacao e erro operacional

Para o app reagir bem, a API deve responder de forma previsivel. Uma coisa e token expirado. Outra e usuario sem permissao para aquele recurso. Outra e falha temporaria do servidor.

O app consegue tomar decisoes melhores quando o backend separa:

• sessao invalida ou expirada;
• usuario autenticado sem autorizacao;
• falha de validacao do request;
• erro temporario que pede retry posterior.

Quando tudo vira erro generico, o mobile tambem responde mal: derruba sessao atoa, reenvia request indevido ou mostra mensagem sem contexto.

12. Checklist para um auth flow mais previsivel

1. Definir estados de bootstrap, nao autenticado e autenticado.
2. Renderizar SplashScreen antes do navigator enquanto a sessao esta indefinida.
3. Guardar token pequeno em armazenamento seguro.
4. Nao usar armazenamento seguro como unica fonte de verdade do estado da conta.
5. Separar access token e refresh token quando a arquitetura pedir isso.
6. Controlar refresh para evitar varias renovacoes concorrentes.
7. Limpar sessao, cache sensivel e fila indevida no logout.
8. Decidir como o app reage ao voltar do background.
9. Combinar com a API o que significa expirar, revogar e revalidar sessao.
10. Testar app fechado, reaberto, sem rede, com sessao vencida e com backend recusando refresh.

13. Erros comuns

• salvar token sensivel em armazenamento inadequado por comodidade;
• liberar rotas antes de terminar bootstrap da sessao;
• usar um unico token eterno;
• deixar cada request tentar refresh por conta propria;
• fazer logout sem limpar dados do usuario anterior;
• nao prever o que acontece quando a biometria muda;
• misturar sessao valida com modo offline sem regra;
• tratar qualquer 401 como erro misterioso de rede.

14. Quando vale revisar a arquitetura de autenticacao

Se o app ja sofre com loop de login, erro 401 sem contexto, refresh instavel, cache herdado no logout ou sincronia ruim entre app e backend, talvez o problema nao seja uma tela. Seja o desenho inteiro da sessao. Nesse ponto, um diagnostico tecnico pode ajudar a revisar fronteira entre mobile, API, seguranca e experiencia do usuario antes de o retrabalho crescer ainda mais.

Autenticacao mobile madura nao e a mais sofisticada. E a mais previsivel. Quando login, token, refresh, bootstrap e logout conversam entre si, o app deixa de surpreender a equipe e o usuario no pior momento: justamente quando ele precisa entrar rapido e confiar que a operacao vai continuar funcionando.

Referencias editoriais: Expo SecureStore, React Navigation auth flow e React Native AppState.