Muffin-OAuth
Muffin-OAuth adds OAuth 2 authorization to the Muffin framework on top of
aioauth-client. It builds authorization URLs, keeps the state parameter
tamper-proof with an HMAC signature, exchanges the authorization code for an access token and
gives you a ready-to-use API client.
Read the documentation for configuration, security details and the full API reference.
Requirements
- Python 3.11 - 3.15
- Muffin >= 3
- Works with
asyncio,TrioandCurio
Install
pip install muffin-oauth
The example application also needs uvicorn:
pip install "muffin-oauth[uvicorn]"
Quickstart
The same route starts the flow and finishes it. Without a code query argument login()
raises ResponseRedirect (Muffin answers 307) to the provider. The provider sends the user
back to redirect_uri with code and state, and the second call exchanges the code for a
token.
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):
# First visit: redirect to GitHub. Callback: validate state, get the token.
client, token, data = await oauth.login("github", request)
user = await client.request("GET", "/user")
return {"login": user["login"], "token": token}
Run it and open http://localhost:8000/login:
uvicorn myapp:app --port 8000
Configuration
| Option | Default | Description |
|---|---|---|
clients |
{} |
Provider name → aioauth-client client options |
redirect_uri |
None |
Callback URL; falls back to the current URL without query |
secret |
important:replace_me_asap! |
HMAC key for the state signature — change it in production |
Options are read from the application config with the OAUTH_ prefix
(OAUTH_CLIENTS, OAUTH_REDIRECT_URI, OAUTH_SECRET), or from environment variables with the
{CFG.NAME}_OAUTH_ prefix — MUFFIN_OAUTH_SECRET by default, JSON is parsed for complex values:
export MUFFIN_OAUTH_SECRET=change-me
export MUFFIN_OAUTH_CLIENTS='{"github": {"client_id": "...", "client_secret": "..."}}'
clients keys are the names registered by aioauth-client (for example github, google,
vk, yandex, gitlab, discord). Every other key of a client entry is passed to its
constructor and ends up in the authorization URL: scope, allow_signup, access_type, ...
API
| Method | Returns | Description |
|---|---|---|
client(name, **params) |
aioauth_client.Client |
Create a configured provider client |
authorize(client, redirect_uri=None, **params) |
str |
Build the authorization URL with a signed state |
login(name, request, redirect_uri=None, headers=None, **params) |
(client, token, data) |
Redirect or exchange the code for a token |
refresh(name, refresh_token, **params) |
await (token, data) |
Exchange a refresh token for a new access token |
login() returns the client with access_token already set, the access token and the raw
provider response. See the API reference for
arguments and return values.
Security
stateis<random token>.<base64url HMAC-SHA512 of that token with secret>; a missing or altered signature answers406 Not Acceptableand the code is never exchanged.- Set your own
secret. The default value is public and lets anyone forge astate. - Without
redirect_urithe plugin uses the current request URL without its query string, so the provider must be registered with that exact URL.
Errors
| Error | When |
|---|---|
OAuthError |
Client is not configured, unknown, or OAuth1 |
ResponseError.BAD_REQUEST (400) |
The provider reported an error (user denied the app) |
ResponseError.NOT_ACCEPTABLE (406) |
state is missing or its signature does not match |
OAuth 2 only
The plugin drives OAuth2 authorization-code flows. OAuth1 providers (twitter, tumblr,
flickr, ...) are registered by aioauth-client, but client() rejects them with OAuthError
because the plugin only looks for the OAuth2 code query argument. Use aioauth_client
directly for OAuth1.
Example
example.py is a working
application with GitHub and Google login and user info rendering:
uv run --group example uvicorn example:app --port 5000
License
Licensed under the MIT license.
Metadata
Release files for muffin-oauth 2.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| muffin_oauth-2.10.0.tar.gz | 6.0 kB | Without provenance | Details for muffin_oauth-2.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| muffin_oauth-2.10.0-py3-none-any.whl | Python 3 | none | any | Details for muffin_oauth-2.10.0-py3-none-any.whl |
Total release size: 11.8 kB
Release files / muffin_oauth-2.10.0.tar.gz
| Download URL | muffin_oauth-2.10.0.tar.gz |
|---|---|
| Size | 6.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
eaf4296ee866a5533559df3c32acd6bb2d7848221fe3dd844f1f1d7f973dce3d
|
|
BLAKE2b-256 checksum How to use checksums |
4989499b9450a80d981d240c7422f1e50ad7ccf6f1703e2ee40b8ed629733e23
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / muffin_oauth-2.10.0-py3-none-any.whl
| Download URL | muffin_oauth-2.10.0-py3-none-any.whl |
|---|---|
| Size | 5.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
534b56def5e3e4bc7c25eb56154f20ca4eb7cae86185b3f0562aa50a87498397
|
|
BLAKE2b-256 checksum How to use checksums |
4a63f6c328a80eef36fc3b285c6ceb955bdf1442742bd083ef82d32917c78a62
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for muffin-oauth 2.10.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.