Tokens criptografados

Por padrão os tokens do Authio são JWTs assinados: qualquer um que tenha o token lê o conteúdo. Com a criptografia ligada, eles viram JWE, que só quem tem a chave abre. Este guia cobre o caminho inteiro, do console até o app em produção. Para o UserInfo em JWT, veja UserInfo assinado e criptografado.

Qual chave usar

Use a chave da plataforma para esconder o conteúdo do access e do refresh token de tudo fora do Authio (navegador, logs, proxies) sem mexer no app. Use a chave do próprio client quando o ID token também não pode trafegar legível, nem mesmo dentro da sua infraestrutura. Em qualquer caso, a criptografia esconde o conteúdo; ela não impede o uso: um access token continua valendo para quem o tiver em mãos.

Checklist

1. Gerar (ou importar) o par de chaves do client e baixar a chave privada.
2. Guardar a chave privada num segredo do app, nunca no repositório.
3. Configurar o app com a chave e fazer o deploy.
4. Só então ligar a criptografia no client, com a chave do próprio client, RSA-OAEP e um algoritmo CBC-HMAC.
5. Configurar as APIs que recebem o access token para validá-lo por introspecção.
6. Testar um login e uma renovação de sessão.

Passo a passo no Authio

1. 1

   Gere o par de chaves e baixe a chave privada

   Em Clients, abra o client e vá em Editar → Segurança → Criptografia de token → Gerar par de chaves. A chave privada aparece uma única vez, em JWK e em PEM: use Baixar JWK (ou copie) antes de fechar o diálogo. O Authio não mostra a chave privada de novo; perdê-la significa gerar outro par.

   Se você já tem uma chave RSA de 2048 a 4096 bits, use Importar chave privada (JWK ou PEM); o kid de uma JWK importada é mantido.

2. 2

   Guarde a chave no app

   Coloque a JWK (o conteúdo do arquivo baixado) num segredo do app: uma variável de ambiente, um key vault. Veja abaixo onde cada biblioteca procura a chave, e faça o deploy do app já com ela.

3. 3

   Ligue a criptografia no client

   Ainda em Segurança → Criptografia de token, preencha e salve:

   Campo	Valor
   Criptografia de token	Ligada
   Chave de criptografia	Chave do próprio client
   Algoritmo JWE	RSA
   Algoritmo de criptografia da chave	RSA-OAEP
   Algoritmo de criptografia do conteúdo	A256CBC-HS512 (ou outro CBC-HMAC; o Authio não criptografa com AES-GCM)

   Tokens criptografados com a chave do client são sempre assinados por dentro, por isso Assinar tokens criptografados fica ligado sozinho. Prefira RSA-OAEP a RSA1_5: algumas bibliotecas, como o Auth.js v5, não abrem RSA1_5.

4. 4

   Teste

   Faça um login: o id_token da resposta do endpoint de token tem cinco partes separadas por ponto (um JWE) e o app abre a sessão normalmente. Depois espere o access token vencer (ou force uma renovação) e confira que a sessão continua.

Configure o seu app

Depois de descriptografado, o ID token é um JWT assinado comum, validado pelo JWKS do realm como sempre. A única coisa nova é a chave privada.

Next.js (Auth.js v5 e NextAuth v4)

A partir da versão 2.2.0, o authio-provider-nextauth descriptografa o ID token sozinho. Coloque a chave privada em AUTH_AUTHIO_ENCRYPTION_KEY: a JWK que o Authio mostrou ao gerar o par, ou o PEM (PKCS#8 ou PKCS#1) quando você importou a chave. Nada muda no código.

AUTH_AUTHIO_ENCRYPTION_KEY='{"kty":"RSA","n":"...","e":"AQAB","d":"...","p":"...","q":"...","dp":"...","dq":"...","qi":"..."}'

No Auth.js v5 os algoritmos saem do próprio token. No NextAuth v4 o openid-client só aceita os algoritmos que conhece: o provider assume os padrões do Authio (RSA-OAEP e A256CBC-HS512); se o client usa outros, informe encryption: { alg, enc } no Authio(). No v4, com a chave configurada, o ID token precisa chegar criptografado: tire a variável se desligar a criptografia.

O access token chega como o Authio emitiu, porque é ele que a sua API recebe. Para ler as claims dele no servidor, ou abrir os tokens de uma renovação que o seu app faz por conta própria, use decryptAuthioToken:

import { decryptAuthioToken } from 'authio-provider-nextauth/v5'
import { decodeJwt } from 'jose'

// Usa AUTH_AUTHIO_ENCRYPTION_KEY; um token que não veio criptografado volta como está
const claims = decodeJwt(await decryptAuthioToken(token.accessToken))

.NET (BFF e OpenID Connect)

No BFF do Authio (Authio.AspNetCore.Bff 0.6.0 ou superior), informe a chave em Authio:Bff:EncryptionKey (a JWK ou o PEM). Ele descriptografa o ID token e o access token de onde saem os papéis e a organização da sessão, no login e a cada renovação, e confere a chave na inicialização.

{
  "Authio": {
    "Bff": {
      "EncryptionKey": "<a JWK privada ou o PEM, vindo de um segredo>"
    }
  }
}

Com o handler de OpenID Connect do ASP.NET Core diretamente, passe a chave em TokenValidationParameters.TokenDecryptionKey.

Qualquer cliente OIDC

1. Receba o id_token do endpoint de token: com cinco partes, ele é um JWE.
2. Descriptografe com a chave privada do client, aceitando o alg e o enc configurados no client (veja o cabeçalho do JWE).
3. O conteúdo é um JWT assinado: valide assinatura, iss, aud, exp e nonce pelo JWKS do realm.
4. Mande o access token para a sua API como veio. Se o app precisar das claims dele, descriptografe uma cópia com a mesma chave.

APIs e resource servers

Uma API não tem a chave do client que pediu o token, então não abre o access token: ela o valida por introspecção. Com o Authio.AspNetCore, configure Authio:Introspection como IntrospectionOnly; sem isso, a API tenta ler o token localmente e recusa o JWE.

{
  "Authio": {
    "Introspection": "IntrospectionOnly"
  }
}

Trocar ou remover a chave

Gerar outro par, importar outra chave ou remover a chave torna ilegível, na hora, todo token criptografado com a chave anterior: as sessões abertas precisam de novo login. Para trocar com o mínimo de impacto:

1. Gere o par novo e baixe a chave privada.
2. Atualize o segredo do app e faça o deploy logo em seguida.
3. Avise que quem estava logado vai entrar de novo.

Remover a chave volta o client para a chave da plataforma e desliga o UserInfo criptografado.

Problemas comuns