csrf

Home > Servir site e arquivos > Proteção CSRF 🚧

Proteção CSRF (TRALCSRFPlugin)

Important

Em desenvolvimento (2.0). Ainda não está numa versão lançada e pode mudar.

Vale para a 2.0 · Nível: intermediário

Em uma frase: o TRALCSRFPlugin recusa com 403 todo pedido que altera estado e não traz o token do próprio cookie, impedindo que outro site use a sessão do seu usuário.

Você vai precisar: RALModuleWebPackage, um TRALWebModule (para amarrar o token à sessão).

Como funciona

Double-submit: o token vai num cookie (ral_csrf, legível por scripts) e a página o devolve no cabeçalho ou no campo do formulário. O token é assinado com HMAC-SHA256 de Secret e, com WebModule ligado, amarrado à sessão: token de outra sessão é recusado. Só métodos que alteram estado são checados (não GET, HEAD, OPTIONS, TRACE, QUERY). Um Origin/Referer de outro site fora de AllowedOrigins também é recusado.

Ligando

uses RALCSRF;

Csrf := TRALCSRFPlugin.Create(Self);
Csrf.Server := Servidor;
Csrf.WebModule := Web;
Csrf.Secret := 'segredo-longo';
Csrf.ExcludePaths.Add('/api/*');   // herdado de TRALPlugin

Num modelo de visão, csrf_token e csrf_field já existem:

<form method="post" action="/clientes">
  {{{csrf_field}}}            <!-- <input type="hidden" name="_csrf" value="..."> -->
  ...
</form>

<body hx-headers='{"X-CSRF-Token": "{{csrf_token}}"}'>

Em código: Csrf.Token(ARequest, AResponse) e Csrf.FieldHTML(ARequest, AResponse).

Propriedades

propriedade	padrão
Secret	vazio	chave do HMAC. Vazio usa uma aleatória do processo: tokens morrem com ele; atrás de balanceador, todos precisam do mesmo
WebModule	nil	amarra o token à sessão
HeaderName	X-CSRF-Token	cabeçalho aceito
FieldName	_csrf	campo de formulário aceito
CookieName	ral_csrf	cookie do token (sem HttpOnly, de propósito)
AllowedOrigins	vazio	origens esquema://host[:porta] de outros sites autorizados
SkipBearer	True	deixa passar Authorization: Bearer (navegador não o envia sozinho)
IncludePaths/ExcludePaths		limitam o plugin (herdados)

Prioridade 650: depois do CORS, antes da autenticação. Recusa: 403 problem+json.

Armadilhas

o que acontece	causa	o que fazer
403 em todo POST de API	o plugin cobre a API de tokens/JSON	ExcludePaths ou SkipBearer
403 após reiniciar	Secret vazio	defina um Secret fixo
403 após login	a sessão mudou (RegenerateSession) e o token estava amarrado à antiga	gere a página de novo depois do login
403 vindo de outro domínio seu	Origin diferente	AllowedOrigins

Veja também

• Páginas e HTMX · Sessões · Segurança para produção · Plugins