OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add auth0/agent-skills --skill auth0-flask
Use when adding session-based login, logout, or user profile to a Flask web application. Integrates auth0-server-python — use even if the user says "add login to my Flask app" or "protect my Flask routes".
npx skills add auth0/agent-skills --skill auth0-flask
Add login, logout, and user profile to a Flask web application using auth0-server-python.
auth0-quickstart skill firstauth0-fastapi-api for FastAPI, or see the Django REST Framework quickstartauth0-react, auth0-vue, or auth0-angular for client-side authauth0-nextjs which handles both client and serverauth0-express or auth0-fastify for session-based authCritical: You must install flask[async] (not just flask). The [async] extra installs asgiref which is required for Flask 2.0+ to support async def route handlers. Without it, async routes will not work. In requirements.txt, use flask[async]>=2.0.0.
Create .env:
AUTH0_DOMAIN is your Auth0 tenant domain (without https://). AUTH0_CLIENT_ID and AUTH0_CLIENT_SECRET come from your Auth0 Application settings. AUTH0_SECRET is used for encrypting session data — generate with openssl rand -hex 64.
In your Auth0 Application settings:
http://localhost:5000/callbackhttp://localhost:5000Create auth.py to initialize the ServerClient with Flask session-based stores. The stores use Flask's built-in session (cookie-based by default) for a stateless setup — no external database needed:
Create one ServerClient instance and reuse it. Never hardcode credentials — always use environment variables.
How this works: Flask's default session is cookie-based (stateless). The SDK encrypts session data (tokens, user profile) with JWE before storing it in the session, so data is both signed and encrypted in the cookie. No server-side database is required.
No store_options or before_request needed: The SDK supports passing store_options (e.g. request/response objects) to store methods. Since these stores use flask.session — which is globally available during a request — they don't need anything from store_options, so you can call SDK methods without passing it. If you implement a custom store that manages cookies directly (instead of using flask.session), you would need to reintroduce store_options with {"request": request, "response": response}.
Cookie size note: Stateless sessions store all data in a cookie (~4KB limit). For most apps this is sufficient. If you store large amounts of session data or hit cookie size limits, switch to stateful setup.
In app.py, set up Flask with the secret key and session configuration:
Critical: app.secret_key must be set for Flask session management. Without it, sessions won't work.
For production: Set SESSION_COOKIE_SECURE=True when deploying with HTTPS. Leaving it as False in production allows session cookies to be sent over unencrypted connections.
start_interactive_login() returns a URL string pointing to Auth0's Universal Login page. You must wrap it in redirect(). Authorization params (scope, redirect_uri) are already configured on the ServerClient.
Pass str(request.url) as the first argument — this is the full callback URL including the authorization code query parameters. Always wrap in try/except since the token exchange can fail (e.g. expired code, CSRF mismatch).
get_user() returns the user's profile from the session, or None if not logged in.
logout() returns the Auth0 logout URL. Redirect the user to it.
Visit http://localhost:5000/login to start the login flow.
For production apps or when session data exceeds cookie size limits, use Flask-Session with Redis to store sessions server-side. Only a session ID is stored in the cookie.
Update app.py to use Redis-backed sessions:
The same FlaskSessionStateStore and FlaskSessionTransactionStore from auth.py work without modification. Flask-Session transparently switches the flask.session backend from cookies to Redis — the stores continue to use flask.session as before.
Routes are identical to the stateless setup — no code changes needed.
| Mistake | Fix |
|---|---|
Hardcoding domain, client_id, or client_secret in source | Always read from environment variables — never embed credentials in code |
Using Authlib or python-jose directly | Not needed; auth0-server-python handles all OAuth/OIDC flows |
Using Flask-Login or Flask-Dance | Not needed; the SDK manages sessions and authentication |
Manually parsing JWTs with jwt.decode() | The SDK handles token validation internally |
Installing flask without [async] extra | Must use flask[async]>=2.0.0 in requirements.txt — without it, async route handlers silently fail |
| Using synchronous route handlers | All routes calling SDK methods must be async def and use await |
Forgetting app.secret_key | Required for Flask session management — without it, sessions silently fail |
Using auth0-fastapi-api in Flask | That package is for FastAPI APIs — use auth0-server-python for Flask |
Passing domain as full URL with https:// | domain should be the bare domain, e.g. my-tenant.us.auth0.com, not https://my-tenant.us.auth0.com |
| Not configuring callback URL in Auth0 Dashboard | Must add http://localhost:5000/callback to Allowed Callback URLs |
Returning start_interactive_login() directly | It returns a URL string, not a response — must wrap in redirect() |
Not handling errors in /callback | complete_interactive_login() can fail — always wrap in try/except |
Calling SDK methods without await | All SDK methods are async — forgetting await returns a coroutine instead of the result |
Passing options positionally to logout() | Use logout(store_options=...) — the first positional parameter is LogoutOptions, not store options |
| Expecting backchannel logout to work | Not supported with cookie-based sessions — delete_by_logout_token is a no-op. Use standard /logout route |
Deploying with SESSION_COOKIE_SECURE=False | Must set to True in production — cookies are sent over HTTP otherwise |
All methods are async:
| Method | Signature | Purpose |
|---|---|---|
start_interactive_login | await auth0.start_interactive_login() | Returns authorization URL string — wrap in redirect() |
complete_interactive_login | await auth0.complete_interactive_login(str(request.url)) | Processes the callback URL, exchanges code for tokens |
get_user | await auth0.get_user() | Returns current session user dict or None |
get_access_token | await auth0.get_access_token() | Returns the access token for calling external APIs |
logout | await auth0.logout() | Returns Auth0 logout URL string |
auth0-express — For server-rendered Express web apps with login/logout sessionsauth0-fastify — For Fastify web applications with session-based authauth0-cli — Manage Auth0 resources from the terminalServerClient configuration:
Route protection pattern:
Environment variables:
AUTH0_DOMAIN — your Auth0 tenant domain (e.g. tenant.us.auth0.com)AUTH0_CLIENT_ID — your Application's client IDAUTH0_CLIENT_SECRET — your Application's client secretAUTH0_SECRET — encryption and session secret keyAUTH0_REDIRECT_URI — callback URL (e.g. http://localhost:5000/callback)import os
from flask import session as flask_session
from auth0_server_python.auth_server.server_client import ServerClient
from auth0_server_python.auth_types import StateData, TransactionData
from auth0_server_python.store import StateStore, TransactionStore
from dotenv import load_dotenv
load_dotenv() # Uses .env by default; pass load_dotenv(".env.local") if credentials are in .env.local
class FlaskSessionStateStore(StateStore):
"""State store that uses Flask's session for persistence."""
def __init__(self, secret: str):
super().__init__({"secret": secret})
async def set(self, identifier, state, remove_if_expires=False, options=None):
data = state.dict() if hasattr(state, "dict") else state
flask_session[identifier] = self.encrypt(identifier, data)
async def get(self, identifier, options=None):
data = flask_session.get(identifier)
if data is None:
return None
decrypted = self.decrypt(identifier, data)
# Ensure to not return a dict, as the underlying SDK expects a StateData instance, not a dict
return StateData(**decrypted) if isinstance(decrypted, dict) else decrypted
async def delete(self, identifier, options=None):
flask_session.pop(identifier, None)
async def delete_by_logout_token(self, claims, options=None):
pass
class FlaskSessionTransactionStore(TransactionStore):
"""Transaction store that uses Flask's session for persistence."""
def __init__(self, secret: str):
super().__init__({"secret": secret})
async def set(self, identifier, state, remove_if_expires=False, options=None):
data = state.dict() if hasattr(state, "dict") else state
flask_session[identifier] = self.encrypt(identifier, data)
async def get(self, identifier, options=None):
data = flask_session.get(identifier)
if data is None:
return None
decrypted = self.decrypt(identifier, data)
# Ensure to not return a dict, as the underlying SDK expects a TransactionData instance, not a dict
return TransactionData(**decrypted) if isinstance(decrypted, dict) else decrypted
async def delete(self, identifier, options=None):
flask_session.pop(identifier, None)
secret = os.getenv("AUTH0_SECRET")
auth0 = ServerClient(
domain=os.getenv("AUTH0_DOMAIN"),
client_id=os.getenv("AUTH0_CLIENT_ID"),
client_secret=os.getenv("AUTH0_CLIENT_SECRET"),
secret=secret,
redirect_uri=os.getenv("AUTH0_REDIRECT_URI"),
state_store=FlaskSessionStateStore(secret=secret),
transaction_store=FlaskSessionTransactionStore(secret=secret),
authorization_params={"scope": "openid profile email"},
)import os
from flask import Flask, redirect, request
from auth import auth0
from dotenv import load_dotenv
load_dotenv()
app = Flask(__name__)
app.secret_key = os.getenv("AUTH0_SECRET")
app.config.update(
SESSION_COOKIE_SECURE=False, # Set to True in production (requires HTTPS)
SESSION_COOKIE_HTTPONLY=True,
SESSION_COOKIE_SAMESITE="Lax",
)@app.route("/")
async def home():
user = await auth0.get_user()
if user:
return f"Hello, {user['name']}! <a href='/profile'>Profile</a> | <a href='/logout'>Logout</a>"
return "Welcome! <a href='/login'>Login</a>"@app.route("/login")
async def login():
authorization_url = await auth0.start_interactive_login()
return redirect(authorization_url)@app.route("/callback")
async def callback():
try:
await auth0.complete_interactive_login(str(request.url))
return redirect("/")
except Exception as e:
return f"Authentication error: {str(e)}", 400@app.route("/profile")
async def profile():
user = await auth0.get_user()
if user is None:
return redirect("/login")
return (
f"<h1>{user['name']}</h1>"
f"<p>Email: {user['email']}</p>"
f"<img src='{user['picture']}' alt='{user['name']}' width='100' />"
f"<p><a href='/logout'>Logout</a></p>"
)@app.route("/logout")
async def logout():
url = await auth0.logout()
return redirect(url)flask runpip install flask-session redisimport os
from flask import Flask, redirect, request
from flask_session import Session
from auth import auth0
from dotenv import load_dotenv
load_dotenv()
app = Flask(__name__)
app.secret_key = os.getenv("AUTH0_SECRET")
app.config.update(
SESSION_TYPE="redis",
SESSION_PERMANENT=True,
SESSION_KEY_PREFIX="auth0:",
SESSION_COOKIE_SECURE=False,
SESSION_COOKIE_HTTPONLY=True,
SESSION_COOKIE_SAMESITE="Lax",
)
Session(app)auth0 = ServerClient(
domain=os.getenv("AUTH0_DOMAIN"), # required
client_id=os.getenv("AUTH0_CLIENT_ID"), # required
client_secret=os.getenv("AUTH0_CLIENT_SECRET"), # required
secret=os.getenv("AUTH0_SECRET"), # required (encryption secret)
redirect_uri=os.getenv("AUTH0_REDIRECT_URI"), # required
state_store=FlaskSessionStateStore(secret=secret), # required
transaction_store=FlaskSessionTransactionStore(secret=secret), # required
authorization_params={"scope": "openid profile email"}, # recommended
)user = await auth0.get_user()
if user is None:
return redirect("/login")