Muffin-OAuth¶
Muffin-OAuth adds OAuth 2 authorization to Muffin on top of
aioauth-client. The plugin is deliberately small: it builds the
authorization URL with a signed state, checks that signature on the callback, exchanges the
authorization code for an access token, and returns an aioauth-client instance that is ready
for API calls.
It does not touch your session or your user model. Store the token wherever your application
keeps state (muffin-session, a cookie, a database) and decide yourself what a successful
login means.
Start here¶
- Usage: the login redirect flow, callback handling, refresh tokens, direct API calls.
- Configuration:
clients,redirect_uri,secret, environment variables. - Security: how
stateis signed, what is rejected, what stays your job. - API reference: plugin methods, arguments, return values, errors.
- Development: local setup, tests, docs, release.
Install¶
pip install muffin-oauth
Python 3.11 - 3.15, Muffin 3 and aioauth-client are required. The plugin is async-native and
runs on asyncio, Trio and Curio.
Minimal example¶
import muffin
from muffin_oauth import OAuthPlugin
app = muffin.Application(
"myapp",
OAUTH_CLIENTS={"github": {"client_id": "...", "client_secret": "...", "scope": "user:email"}},
OAUTH_REDIRECT_URI="http://localhost:8000/login",
)
oauth = OAuthPlugin(app)
@app.route("/login")
async def login(request):
client, token, data = await oauth.login("github", request)
user = await client.request("GET", "/user")
return {"login": user["login"]}
How a login happens¶
Browser Your app Provider
| GET /login | |
|--------------------->| login(): no code |
| 307 Location | authorize() signs state |
|<---------------------| |
| GET authorize?state=<random>.<hmac>&redirect_uri |
|--------------------------------------------------->|
| GET /login?code=...&state=... |
|<---------------------------------------------------|
| | login(): verify state, |
| | get_access_token(code) |
| |---------------------------->|
| |<----------------------------|
| 200 {..} | (client, token, data) |
|<---------------------| |
The same route handles both steps, which is why the callback URL equals the login URL unless
you configure redirect_uri differently.
OAuth 2 only¶
OAuth1 providers (twitter, tumblr, flickr, ...) exist in aioauth-client, but
OAuthPlugin.client() rejects them with OAuthError: the plugin only looks for the OAuth2
code query argument, while OAuth1 providers answer with oauth_token and oauth_verifier.
Use aioauth_client directly if you need OAuth1.