Skip to main content

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.

Documentation Tests Status PyPI Version Python Versions

Requirements

  • Python 3.11 - 3.15
  • Muffin >= 3
  • Works with asyncio, Trio and Curio

Install

pip install muffin-oauth

The example application also needs uvicorn and muffin-session:

pip install "muffin-oauth[uvicorn]" muffin-session

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

  • state is <sha256 of random>.<base64url HMAC-SHA512 of that hash with secret>; a missing or altered signature answers 406 Not Acceptable and the code is never exchanged.
  • Set your own secret. The default value is public and lets anyone forge a state.
  • Without redirect_uri the 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 or unknown to aioauth-client
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 the plugin never requests a request token and only looks for the OAuth2 code query argument, so an OAuth1 round trip cannot complete. Use aioauth_client directly for OAuth1.

Example

example.py is a working application with GitHub and Google login, user info rendering and muffin-session:

uv run --group example uvicorn example:app --port 5000

License

Licensed under the MIT license.

Metadata

Release files for muffin-oauth 2.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for muffin-oauth 2.9.0
File Size Uploaded Provenance Actions
muffin_oauth-2.9.0.tar.gz 5.9 kB Without provenance Details for muffin_oauth-2.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for muffin-oauth 2.9.0
File Interpreter ABI Platform Actions
muffin_oauth-2.9.0-py3-none-any.whl Python 3 none any Details for muffin_oauth-2.9.0-py3-none-any.whl

Total release size: 11.7 kB

Release files / muffin_oauth-2.9.0.tar.gz

Download URL muffin_oauth-2.9.0.tar.gz
Size 5.9 kB
Tags Source
SHA-256 checksum
How to use checksums
ade7e415dfd9fe2bdfa2ba8148248bf881965357bb5a2cabb0cffc60d0fa4f4a
BLAKE2b-256 checksum
How to use checksums
d3cb69fc4fdbfe718bf1b276cb080cafbc5c2836a9dd2f26b902bc601dedce84
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.9.0-py3-none-any.whl

Download URL muffin_oauth-2.9.0-py3-none-any.whl
Size 5.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a7616f771370111a76fec353f4b857d71d41f471a3ac03c08511185cba34e6d8
BLAKE2b-256 checksum
How to use checksums
5feceed00a42370ec8f8b41f4108510466bcecd1b7bfae0747c1ccca4a295856
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.9.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.

Release history Release notifications | RSS feed

This release

2.9.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page