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:

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

  • state is <random token>.<base64url HMAC-SHA512 of that token 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, 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)

Source distribution for muffin-oauth 2.10.0
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)

Table of built distributions (wheels) for muffin-oauth 2.10.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

2.10.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