JSONAISTUDIO
Azure · Cloudintermediate

Azure Static Web Apps — staticwebapp.config.json

The staticwebapp.config.json that controls routing, role-based authorization, custom auth, fallback for client-side routers, and response overrides for an Azure Static Web App.

azurestatic-web-appsroutingauthspa

Preview

{
  "routes": [
    {
      "route": "/admin/*",
      "allowedRoles": [
        "administrator"
      ]
    },
    {
      "route": "/api/*",
      "allowedRoles": [
        "authenticated"
      ]
    },
    {
      "route": "/login",
      "rewrite": "/.auth/login/aad"
    },
    {
      "route": "/logout",
      "redirect": "/.auth/logout"
    },
    {
      "route": "/old-path",
      "redirect": "/new-path",
      "statusCode": 301
    }
  ],
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": [
      "/images/*.{png,jpg,gif}",
      "/css/*",
      "/js/*"
    ]
  },
  "responseOverrides": {
    "401": {
      "redirect": "/login",
      "statusCode": 302
    },
    "403": {
      "rewrite": "/403.html"
    },
    "404": {
      "rewrite": "/404.html"
    }
  },
  "globalHeaders": {
    "X-Content-Type-Options": "nosniff",
    "Content-Security-Policy": "default-src 'self'; img-src 'self' data:"
  },
  "mimeTypes": {
    ".json": "application/json",
    ".webmanifest": "application/manifest+json"
  }
}

AI actions

Documentation

Purpose

Configure the edge behavior of an Azure Static Web App: which routes need which roles, how unmatched routes fall back to the SPA shell, and how errors are handled.

When to use

Deploying a single-page app (React/Vue/Angular) to Azure Static Web Apps that needs client-side routing, protected sections, or custom auth providers.

Required fields

  • routes — per-path rules for auth, redirects and rewrites
  • navigationFallback — the SPA fallback for unmatched navigation requests

Optional fields

  • responseOverrides — custom pages for 401/403/404 responses
  • auth — custom identity provider registrations
  • globalHeaders — headers applied to every response
  • mimeTypes — extension-to-content-type mappings

Best practices

  • Exclude static assets from navigationFallback so images and JS are served directly.
  • Gate protected routes with allowedRoles rather than checking auth in client code alone.
  • Set security headers (CSP, X-Content-Type-Options) in globalHeaders.

Security considerations

  • Do not place client secrets in this file; auth provider secrets go in application settings.
  • Return 404 (not 403) for protected admin routes to avoid revealing their existence.
  • Keep a strict Content-Security-Policy to limit XSS blast radius.

Related templates

Related articles