📋 Índice

1. Variáveis de Ambiente Obrigatórias
2. Configuração de JWT
3. Configuração de Rate Limiting
4. Configuração de CORS
5. Configuração de HTTPS
6. Checklist de Deploy

---

🔐 Variáveis de Ambiente Obrigatórias

Desenvolvimento

# JWT Secret (pode usar valor padrão em dev)
JWT__SIGNINGKEY=dev-only-change-me

# CORS (pode usar wildcard em dev)
# Configurado em appsettings.json

---

🔑 Configuração de JWT

Gerar Secret Forte

Linux/Mac:

openssl rand -base64 32

PowerShell (Windows):

[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 }))

Online (não recomendado para produção):

• Use apenas para desenvolvimento
• Nunca compartilhe o secret gerado

Rotação de Secrets

Para rotacionar o secret JWT:

1. Gerar novo secret (usando método acima)
2. Atualizar variável de ambiente JWT__SIGNINGKEY
3. Reiniciar aplicação
4. Nota: Tokens antigos serão invalidados

---

⚡ Configuração de Rate Limiting

Limites Padrão

Tipo de Endpoint	Limite	Janela
Auth (login)	5 req/min	1 minuto
Feed (leitura)	100 req/min	1 minuto
Write (escrita)	30 req/min	1 minuto
Global	60 req/min	1 minuto

Configuração via appsettings.json

{
  "RateLimiting": {
    "PermitLimit": 60,        // Requisições por janela
    "WindowSeconds": 60,      // Janela em segundos (60 = 1 minuto)
    "QueueLimit": 0           // Limite de fila (0 = sem fila, rejeita imediatamente)
  }
}

Configuração via Variáveis de Ambiente

RateLimiting__PermitLimit=60
RateLimiting__WindowSeconds=60
RateLimiting__QueueLimit=0

Resposta quando Limite Excedido

Status Code: 429 Too Many Requests

Headers:

Retry-After: 60

Body:

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please try again later.",
  "instance": "/api/v1/auth/social"
}

Ajustando Limites

Para ajustar limites específicos, edite Program.cs:

// Auth: 5 req/min
options.AddFixedWindowLimiter("auth", limiterOptions =>
{
    limiterOptions.PermitLimit = 5;  // Ajuste aqui
    limiterOptions.Window = TimeSpan.FromMinutes(1);
});

---

🌐 Configuração de CORS

Produção (OBRIGATÓRIO)

Não pode usar wildcard (*) em produção!

{
  "Cors": {
    "AllowedOrigins": [
      "https://app.Arah.com",
      "https://www.Arah.com"
    ]
  }
}

Ou via variáveis de ambiente:

Cors__AllowedOrigins__0=https://app.Arah.com
Cors__AllowedOrigins__1=https://www.Arah.com

Desenvolvimento

{
  "Cors": {
    "AllowedOrigins": [ "*" ]
  }
}

Validação Automática

A aplicação valida automaticamente em produção:

• ✅ Origins não podem ser vazios
• ✅ Wildcard (*) não permitido
• ✅ Erro claro se configuração inválida

---

🔒 Configuração de HTTPS

Produção

HTTPS é obrigatório em produção. A aplicação:

1. Redireciona HTTP para HTTPS automaticamente
2. Configura HSTS (HTTP Strict Transport Security):
   • Max-Age: 365 dias
   • IncludeSubDomains: habilitado
   • Preload: habilitado

Certificados SSL/TLS

Configure certificados no servidor web (Nginx, IIS, etc.) ou use serviços como:

• Let's Encrypt (gratuito)
• Cloudflare (gratuito com proxy)
• AWS Certificate Manager
• Azure App Service (gerenciado)

Desenvolvimento

HTTPS é desabilitado em desenvolvimento para facilitar testes locais.

---

Content-Security-Policy (CSP)

O CSP é configurado dinamicamente:

• API endpoints: CSP mais restritivo (sem unsafe-inline ou unsafe-eval)
• DevPortal/Swagger: CSP mais permissivo (necessário para funcionamento)

Não é necessário configurar manualmente - são aplicados automaticamente.

---

✅ Checklist de Deploy

Após o Deploy

• Testar autenticação (login funciona)
• Testar rate limiting (429 retornado quando excedido)
• Verificar security headers (presentes em todas as respostas)
• Testar CORS (frontend consegue fazer requisições)
• Verificar HTTPS (redirecionamento funciona)
• Verificar HSTS (header presente)

🚨 Troubleshooting

Erro: "JWT SigningKey must be configured"

Causa: Variável de ambiente JWT__SIGNINGKEY não configurada.

Solução:

export JWT__SIGNINGKEY="seu-secret-aqui"
# Ou configure no servidor/container

Erro: "Cors:AllowedOrigins must be configured"

Causa: CORS não configurado ou usando wildcard em produção.

Solução:

{
  "Cors": {
    "AllowedOrigins": ["https://app.Arah.com"]
  }
}

Rate Limiting muito restritivo

Causa: Limites padrão podem ser muito baixos para seu caso.

Solução: Ajuste em appsettings.json ou Program.cs:

{
  "RateLimiting": {
    "PermitLimit": 120,  // Aumentar limite
    "WindowSeconds": 60
  }
}

Security Headers não aparecem

Causa: Middleware não está sendo executado.

Solução: Verificar ordem dos middlewares em Program.cs. SecurityHeadersMiddleware deve ser um dos primeiros.

---

📚 Referências

• ASP.NET Core Security
• Rate Limiting
• CORS
• HSTS
• OWASP Security Headers

---

🔐 Autenticação de Dois Fatores (2FA)

A API suporta autenticação de dois fatores usando TOTP (Time-based One-Time Password).

Fluxo de 2FA

1. Usuário faz login social → Se 2FA habilitado, recebe 2FA_REQUIRED:{challengeId}
2. Usuário envia código TOTP via POST /api/v1/auth/2fa/verify → Recebe JWT
3. Alternativamente, usuário pode usar recovery code via POST /api/v1/auth/2fa/recover

Recovery Codes

Durante a configuração de 2FA, o usuário recebe recovery codes que podem ser usados caso perca acesso ao dispositivo TOTP. Guarde esses códigos em local seguro.

---

📚 Documentação Adicional

• Security Audit - Checklist completo de segurança e guia de penetration testing
• Fase 5: Segurança Avançada - Resumo completo das implementações de segurança avançada

---

Última atualização: 2026-01-15