API reference¶
muffin_oauth exports OAuthPlugin (aliases OAuth and Plugin) and OAuthError.
from muffin_oauth import OAuthError, OAuthPlugin
OAuthPlugin¶
muffin.plugins.BasePlugin subclass, name = "oauth", available as app.plugins["oauth"]
after setup.
Options: clients, redirect_uri, secret.
client(client_name, **params) -> aioauth_client.Client¶
Create a provider client from the registry.
client_namemust be present inclientsand registered byaioauth-client.- Only OAuth2 clients are accepted; an OAuth1 provider (
twitter, ...) raisesOAuthError. paramsare merged over the configured client entry (dict(config, **params)), so a token can be supplied at call time.- The client gets the default logger of
aioauth-client;login()andrefresh()pass the application logger instead.
Raises OAuthError("Unconfigured client: <name>"),
OAuthError("Unsupported services: <name>") or OAuthError("OAuth1 is not supported: <name>").
client = oauth.client("github", access_token="...")
authorize(client, redirect_uri=None, **params) -> str¶
Build the authorization URL for an already created client.
- Generates a
statevalue (<random token>.<signature>) and signs it withsecret. - Passes
redirect_uriand every extraparamsentry toclient.get_authorize_url(); extraparamswin over the entries of the client configuration. - Stateless: nothing is stored. The callback must still be verified by
login().
url = oauth.authorize(oauth.client("github"), "http://localhost:8000/callback")
async login(client_name, request, redirect_uri=None, headers=None, **params) -> (client, token, data)¶
Run one step of the authorization-code flow.
- Without a
codequery parameter: builds the URL withauthorize()and raisesmuffin.ResponseRedirect(a307response). - With a
code: validatesstate, then callsclient.get_access_token(code, redirect_uri=..., headers=...). redirect_uridefaults tocfg.redirect_uri, then tostr(request.url.with_query("")).paramsgo to the authorization URL;headersgo to the token request.- Returns the client (with
access_tokenset), the access token and the raw provider response.
Raises OAuthError for an unknown client, ResponseError.BAD_REQUEST (400) when the
provider reports an error (an error query argument, e.g. the user denied the app) and
ResponseError.NOT_ACCEPTABLE (406) for a missing or badly signed state.
client, token, data = await oauth.login("github", request)
refresh(client_name, refresh_token, **params) -> awaitable¶
Return the coroutine of client.get_access_token(refresh_token,
grant_type="refresh_token", **params), which resolves to (token, data).
token, data = await oauth.refresh("github", refresh_token)
The plugin does not store the new token.
OAuthError¶
Exception subclass raised by the plugin itself (not by aioauth-client, which raises its own
OAuthError). Raised for an unconfigured or unsupported client, i.e. before any network call.
sign(msg, key) -> str¶
muffin_oauth.plugin.sign is the helper used for the state signature: base64url of
HMAC-SHA512. It is importable but not part of the documented API; state verification goes
through login().