Trusted host middleware in FastAPI

Introduction

Trusted host middleware helps your app accept requests only from safe website addresses. It blocks requests from unknown or harmful sources.

When you want to stop fake or harmful requests from unknown websites.

When your app should only respond to specific domain names you control.

To protect your app from host header attacks.

When deploying your app behind proxies or load balancers and you want to ensure correct host validation.

Syntax

FastAPI

from fastapi import FastAPI
from starlette.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()

app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["example.com", "www.example.com"]
)

The allowed_hosts list contains the hostnames your app trusts.

Use "*" to allow all hosts, but this disables protection.

Examples

Only requests with host header myapp.com are accepted.

FastAPI

app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["myapp.com"]
)

Accepts requests from local development addresses.

FastAPI

app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["localhost", "127.0.0.1"]
)

Allows all hosts (not recommended for production).

FastAPI

app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["*"]
)

Sample Program

This FastAPI app only accepts requests where the host header is "example.com" or "www.example.com". Other hosts get blocked.

FastAPI

from fastapi import FastAPI
from starlette.middleware.trustedhost import TrustedHostMiddleware
from fastapi.responses import PlainTextResponse

app = FastAPI()

app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["example.com", "www.example.com"]
)

@app.get("/")
async def read_root():
    return PlainTextResponse("Hello from trusted host!")

Important Notes

TrustedHostMiddleware returns a 400 error if the host is not allowed.

Make sure to include all domain variants your app uses (with and without www).

Use this middleware early in your middleware stack for best protection.

Summary

Trusted host middleware blocks requests from unknown hosts.

Configure it with a list of allowed hostnames.

It helps protect your app from host header attacks.

Practice

1. What is the main purpose of the TrustedHostMiddleware in FastAPI?

easy

A. To block requests from hosts not in the allowed list

B. To speed up the response time of the app

C. To handle database connections securely

D. To manage user authentication tokens

Solution

1. Step 1: Understand middleware role

   The TrustedHostMiddleware is designed to filter incoming requests based on their host header.

2. Step 2: Identify its security purpose

   It blocks requests from hosts not explicitly allowed to protect against host header attacks.

3. Final Answer:

   To block requests from hosts not in the allowed list -> Option A

4. Quick Check:

   TrustedHostMiddleware blocks unknown hosts = D [OK]

Hint: Remember: Trusted hosts means allowed hosts only [OK]

Common Mistakes:

• Confusing it with authentication middleware
• Thinking it speeds up app performance
• Assuming it manages database connections

2. Which of the following is the correct way to add TrustedHostMiddleware to a FastAPI app?

easy

A. app.middleware(TrustedHostMiddleware, allowed=['example.com'])

B. app.add_middleware(TrustedHostMiddleware, allowed_hosts=['example.com'])

C. app.use(TrustedHostMiddleware, hosts=['example.com'])

D. app.add_middleware(TrustedHostMiddleware, hosts=['example.com'])

Solution

1. Step 1: Recall FastAPI middleware syntax

   FastAPI uses app.add_middleware() with the middleware class and keyword arguments.

2. Step 2: Check correct argument name

   The correct argument for allowed hosts is allowed_hosts, not hosts or allowed.

3. Final Answer:

   app.add_middleware(TrustedHostMiddleware, allowed_hosts=['example.com']) -> Option B

4. Quick Check:

   Use add_middleware with allowed_hosts = C [OK]

Hint: Use add_middleware and allowed_hosts keyword [OK]

Common Mistakes:

• Using wrong method like app.use()
• Passing 'hosts' instead of 'allowed_hosts'
• Incorrect argument names like 'allowed'

3. Given this FastAPI app code snippet, what will happen if a request comes from host 'malicious.com'?

from fastapi import FastAPI
from starlette.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()
app.add_middleware(TrustedHostMiddleware, allowed_hosts=['example.com', 'localhost'])

@app.get('/')
def read_root():
    return {'message': 'Hello World'}

medium

A. The request will be redirected to 'example.com'

B. The request will succeed and return 'Hello World'

C. The app will crash with an exception

D. The request will be blocked with a 400 Bad Request error

Solution

1. Step 1: Check allowed hosts list

   The allowed hosts are 'example.com' and 'localhost'. 'malicious.com' is not in this list.

2. Step 2: Understand middleware behavior on unknown hosts

   TrustedHostMiddleware blocks requests from hosts not in the allowed list by returning a 400 error.

3. Final Answer:

   The request will be blocked with a 400 Bad Request error -> Option D

4. Quick Check:

   Unknown host causes 400 error = A [OK]

Hint: Requests from hosts not allowed get 400 error [OK]

Common Mistakes:

• Assuming the request passes through
• Thinking the app crashes on unknown hosts
• Believing the request is redirected automatically

4. Identify the error in this FastAPI app setup using TrustedHostMiddleware:

from fastapi import FastAPI
from starlette.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()
app.add_middleware(TrustedHostMiddleware, allowed_hosts='example.com')

@app.get('/')
def home():
    return {'msg': 'Welcome'}

medium

A. The route function must be async

B. TrustedHostMiddleware is not imported correctly

C. allowed_hosts should be a list, not a string

D. Missing middleware initialization parameters

Solution

1. Step 1: Check allowed_hosts argument type

   The allowed_hosts parameter expects a list of strings, but a single string was given.

2. Step 2: Understand impact of wrong type

   Passing a string instead of a list will cause the middleware to treat each character as a host, leading to incorrect behavior or errors.

3. Final Answer:

   allowed_hosts should be a list, not a string -> Option C

4. Quick Check:

   allowed_hosts must be list = A [OK]

Hint: allowed_hosts always needs a list, not a string [OK]

Common Mistakes:

• Passing a single string instead of list
• Thinking route functions must be async
• Assuming import is incorrect without error

5. You want to allow requests from any subdomain of example.com and also from localhost. Which allowed_hosts list correctly configures TrustedHostMiddleware for this?

hard

A. ['*.example.com', 'localhost']

B. ['example.com', 'localhost']

C. ['example.com/*', 'localhost']

D. ['*example.com', 'localhost']

Solution

1. Step 1: Understand wildcard usage in allowed_hosts

   TrustedHostMiddleware supports wildcards like *.example.com to allow all subdomains.

2. Step 2: Check each option for correct wildcard syntax

   ['*.example.com', 'localhost'] uses '*.example.com' which correctly matches all subdomains; others use incorrect patterns.

3. Final Answer:

   ['*.example.com', 'localhost'] -> Option A

4. Quick Check:

   Use '*.example.com' for subdomains = B [OK]

Hint: Use '*.domain.com' to allow all subdomains [OK]

Common Mistakes:

• Using 'example.com/*' which is invalid
• Using '*example.com' missing dot after *
• Not using wildcard for subdomains