CORS, IIS e configurações por ambiente

Resumo

APIs raramente são consumidas pela mesma origem. Aqui configuramos CORS de forma segura, entendemos a integração com o IIS e vemos como ter comportamento diferente por ambiente com appsettings.{Environment}.json.

1. Objetivos de Aprendizagem#

• Configurar uma política de CORS explícita e segura.
• Entender o papel do módulo ASP.NET Core no IIS (UseIISIntegration).
• Sobrescrever configurações por ambiente com arquivos appsettings.{Environment}.json.

2. Pré-requisitos#

• Program.cs organizado com métodos de extensão (tópico 16.2).

3. Conceito#

CORS (Cross-Origin Resource Sharing) é um mecanismo do navegador: ele bloqueia requisições de uma origem (esquema+host+porta) diferente da API, a menos que a API responda com os cabeçalhos permitindo aquela origem. O porquê: proteger o usuário de sites maliciosos que tentam consumir APIs autenticadas em seu nome.

No IIS, o ASP.NET Core roda em processo (Microsoft.AspNetCore.Server.IIS), com o IIS atuando como proxy reverso. AddControllers e o ASP.NET Core Module cuidam da ponte; em código, UseForwardedHeaders/UseIISIntegration ajustam o encaminhamento.

Ambientes: o sistema de configuração carrega appsettings.json e depois appsettings.{ASPNETCORE_ENVIRONMENT}.json, com o segundo sobrescrevendo o primeiro. Assim você mantém uma base comum e ajusta só o que muda.

4. Mão na Massa#

4.1. Setup#

Sem pacotes extras — CORS e integração IIS já vêm no metapacote do SDK Web.

4.2. Implementação Passo a Passo#

1. Adicione a política de CORS em ServiceExtensions.cs:

public static IServiceCollection ConfigureCors(this IServiceCollection services) =>
    services.AddCors(options =>
    {
        options.AddPolicy("CatalogCorsPolicy", policy =>
            policy.WithOrigins("https://app.catalog.local")
                  .WithMethods("GET", "POST", "PUT", "PATCH", "DELETE")
                  .WithHeaders("Content-Type", "Authorization"));
    });

2. Configure a integração com IIS:

public static IServiceCollection ConfigureIisIntegration(this IServiceCollection services) =>
    services.Configure<IISServerOptions>(options =>
    {
        options.AutomaticAuthentication = false;
    });

3. Crie appsettings.Development.json sobrescrevendo apenas o nível de log:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

4.3. Executando#

dotnet run

Requisições de https://app.catalog.local passam; qualquer outra origem é bloqueada pelo navegador.

5. Exemplo Completo#

Program.cs (trecho):

builder.Services.ConfigureCors();
builder.Services.ConfigureIisIntegration();
builder.Services.ConfigureControllers();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseCors("CatalogCorsPolicy"); // depois de UseRouting/UseHttpsRedirection, antes de UseAuthorization
app.UseAuthorization();
app.MapControllers();
app.Run();

6. Boas Práticas e Armadilhas#

Atenção

AllowAnyOrigin() não pode ser combinado com AllowCredentials() — o navegador rejeita. E AllowAnyOrigin em uma API autenticada é um risco de segurança sério.

7. Segurança e Produção#

• CORS permissivo (*) expõe a API a qualquer site; sempre restrinja origens em produção.
• Atrás do IIS/proxy, configure ForwardedHeaders para que o esquema/host reais cheguem à aplicação (importante para redirecionamento HTTPS e geração de links).

8. Exercícios#

• Fácil: adicione uma segunda origem permitida à política.
• Médio: crie appsettings.Production.json que eleve o LogLevel.Default para Warning.
• Desafio: simule um proxy reverso e configure UseForwardedHeaders para preservar X-Forwarded-Proto.

9. Resumo#

Configuramos uma política de CORS restritiva, ajustamos a integração com IIS e vimos como appsettings.{Environment}.json sobrescreve a configuração base por ambiente.

10. Próximos Passos#

Fechamos o módulo entendendo o middleware, a base do pipeline HTTP.

11. Referências#

• Microsoft Learn — Habilitar CORS no ASP.NET Core
• Microsoft Learn — Hospedar ASP.NET Core no IIS
• Microsoft Learn — Configuração no ASP.NET Core