Add Session Middleware
Set up session middleware to manage your application's authenticated sessions.
To manage the user's authenticated state, you'll need to add Wristband's session middleware to your application. This middleware attaches a request.state.session
object to each incoming request, which stores information about the authenticated user. The session data is securely stored in an encrypted cookie, and on subsequent requests, the middleware automatically decrypts the cookie and restores the session state.
Built-in CSRF Protection
Wristband's session middleware automatically provides CSRF protection using the synchronizer token pattern.
Configure Session Middleware
To enable session management, add the Wristband SDK’s SessionMiddleware
to your FastAPI application. You'll need to provide a secret (at least 32 characters long) as the secret_key
value. You can generate a secure secret using 1Password's password generator.
Disabling Secure Session Cookies in Local Development
By default, session cookies are marked as
secure
, meaning they are only sent over HTTPS connections. Most browsers make an exception forlocalhost
and allow secure cookies to be sent over HTTP (e.g.,http://localhost
). However, some browsers, such as Safari, enforce stricter rules and never send secure cookies over HTTP, even forlocalhost
.If you need to disable the secure flag for local development, set
secure=False
inSessionMiddleware
. However, be sure to restoresecure=True
in production to protect session data.
Cross-Domain Session Middleware Configuration
If your frontend and backend are hosted on different domains, you must configure
SessionMiddleware
to explicitly set thecsrf_cookie_domain
. For example, if you have a React frontend hosted atdashboard.yourapp.com
and your FastAPI backend is hosted atapi.yourapp.com
, you must setcsrf_cookie_domain="yourapp.com"
to ensure the CSRF cookie is accessible across both domains.
# src/main.py
from fastapi import FastAPI
from wristband.fastapi_auth import SessionMiddleware
def create_app() -> FastAPI:
app = FastAPI()
# Enable Wristband's session middlware on all routes.
app.add_middleware(SessionMiddleware, secret_key="<your-generated-secret>")
# Your other application setup...
# src/main.py
from fastapi import FastAPI
from wristband.fastapi_auth import SessionMiddleware
def create_app() -> FastAPI:
app = FastAPI()
# Enable Wristband's session middlware on all routes.
app.add_middleware(SessionMiddleware, secret_key="<your-generated-secret>", secure=False)
# Your other application setup...
# src/main.py
from fastapi import FastAPI
from wristband.fastapi_auth import SessionMiddleware
def create_app() -> FastAPI:
app = FastAPI()
# Enable Wristband's session middlware on all routes.
app.add_middleware(SessionMiddleware, secret_key="<your-generated-secret>", csrf_cookie_domain="<your-application-root-domain>")
# Your other application setup...
Updated about 12 hours ago
Next, you'll use the Wristband SDK to create the necessary authentication endpoints in your FastAPI server.