Skip to main content

:::warning AUTO-GENERATED — do not edit This page is generated from the MCP server snapshot content/backend-mcp.json. Edit the source MCP server (not this file), then run npm run generate. :::

Apply @require_auth / @require_role and verify the JWKS validation path

When to use: A route must be protected — either any authenticated user (@require_auth) or a specific role (@require_role).

Prerequisites​

  • The route handler already exists (see create-endpoint).
  • You know whether the route is auth-only or role-gated, and which role.

Steps​

Step 1: Fetch the canonical auth/authorization pattern.​

Tools: get_auth_pattern

Step 2: Decorate the route with @require_auth for authenticated access, or @require_role('<role>') for role-gated access.​

Step 3: Confirm the JWKS validation path is wired: the token signature is verified against the identity provider's JWKS, not merely decoded.​

Tools: get_auth_pattern

Step 4: Verify a request with no/invalid token returns 401 and a valid token passes.​

Tools: validate_backend_endpoint

Full recipe definition​

The complete machine-readable recipe as returned by the MCP server:

{
  "id": "add-auth-guard",
  "title": "Apply @require_auth / @require_role and verify the JWKS validation path",
  "when": "A route must be protected — either any authenticated user (@require_auth) or a specific role (@require_role).",
  "prerequisites": [
    "The route handler already exists (see create-endpoint).",
    "You know whether the route is auth-only or role-gated, and which role."
  ],
  "steps": [
    {
      "action": "Fetch the canonical auth/authorization pattern.",
      "tools": [
        "get_auth_pattern"
      ],
      "note": "Returns the exact decorator import path and usage. Do not invent a custom token flow."
    },
    {
      "action": "Decorate the route with @require_auth for authenticated access, or @require_role('<role>') for role-gated access.",
      "files": [
        "src/routes/<domain>_routes.py"
      ],
      "note": "Order matters: the auth decorator wraps the Flask route. Follow the template's decorator ordering exactly."
    },
    {
      "action": "Confirm the JWKS validation path is wired: the token signature is verified against the identity provider's JWKS, not merely decoded.",
      "tools": [
        "get_auth_pattern"
      ],
      "note": "The pattern verifies signature + audience + expiry via JWKS. A decode-without-verify is a security bug — do not accept it."
    },
    {
      "action": "Verify a request with no/invalid token returns 401 and a valid token passes.",
      "tools": [
        "validate_backend_endpoint"
      ],
      "note": "Cover this with a test (see add-tests): 401 without token, happy path with a fake JWT."
    }
  ],
  "filesToCreate": [],
  "validation": [
    "Unauthenticated request returns 401.",
    "Role-gated route returns 403 for a valid token lacking the role.",
    "Token signature is validated against JWKS (not just base64-decoded)."
  ],
  "doneCriteria": [
    "Every protected route carries @require_auth (and @require_role where required).",
    "JWKS signature validation confirmed on the auth path."
  ],
  "commonMistakes": [
    "Decoding the JWT without verifying its signature against JWKS.",
    "Applying the decorator in the wrong order so Flask never invokes it.",
    "Hard-coding a role check inside the handler instead of using @require_role.",
    "Building a bespoke auth flow instead of using the provided decorators."
  ],
  "relatedRecipes": [
    "create-endpoint",
    "add-tests",
    "run-verify"
  ]
}